PrestaShop module stopped working after an update

Four families of causes, not one

A PrestaShop module stops working after an update, and the symptom varies: a block has vanished from the front office, an admin page returns an error, or the whole site goes down. Behind those symptoms you will almost always find one of four causes: a lost hook, a conflicting override, a dependency removed from the core, or a cache left in an inconsistent state.

Identifying the right family first saves hours.

Cause 1: the hook is no longer registered

Symptom: the module is active, its configuration is intact, but its content no longer appears.

Hook names have changed over the versions. Old names such as hookHeader became hookDisplayHeader, and some hook points disappeared altogether. An old module still installs, but no longer displays.

Check the real state in the database:

SELECT h.name AS hook, m.name AS module, hm.position
FROM ps_hook_module hm
JOIN ps_hook h ON h.id_hook = hm.id_hook
JOIN ps_module m ON m.id_module = hm.id_module
WHERE m.name = 'nom_du_module';

If the expected hook is missing, register it again from the Positions page in the back office, or by reinstalling the module, having first checked that uninstalling it does not wipe its data.

Look at ps_hook_module_exceptions too: an exception added to hide a block on one specific page sometimes ends up hiding it everywhere.

The opposite case exists as well: a module that re-registers itself on a hook after every update, because its install method is being replayed. There the fix belongs in the module, not the database.

Cause 2: a conflicting override

Symptom: a fatal error about a class already declared, or a core feature behaving inconsistently.

PrestaShop allows one override per class, and no more. Two modules overriding Cart or Product collide, and the second one wins silently.

The file to know about is var/cache/prod/class_index.php. It holds the mapping between each class and the file that implements it. Until it is regenerated, an override you have added or removed is simply not taken into account, which produces fatal errors that make no sense.

The reflex after any change in override/:

rm -f var/cache/prod/class_index.php
rm -rf var/cache/prod/*

To test whether an override is to blame, temporarily rename the override/ directory to override_off/ and reload. If the site comes back, you have narrowed down the family of causes.

Cause 3: a dependency removed from the core

This has been the dominant cause since PrestaShop 9, and the most brutal: an immediate fatal error on a class that cannot be found.

PrestaShop 9 removed several long-standing libraries:

• Swift Mailer replaced by Symfony Mailer;
• Guzzle replaced by Symfony HTTP Client;
• League Tactician replaced by Symfony Messenger;
• sensio/framework-extra-bundle removed, so route and template annotations no longer work.

Any module declaring use GuzzleHttp\Client; or use League\Tactician\...; throws a fatal error as soon as it loads.

Spot the modules concerned before you even migrate:

grep -rl "GuzzleHttp\|League\\\\Tactician\|Swift_Mailer" modules/

On top of that, FrameworkBundleAdminController is deprecated in favour of PrestaShopAdminController, and admin controllers now have to be declared as services with dependency injection. A module whose back office controller returns a 500 error after the move to 9 is almost always in this category.

Finally, back office authentication has been moved entirely onto Symfony: single sign-on or two-factor modules that relied on the legacy cookie stop working.

Cause 4: a cache left in an inconsistent state

Symptom: erratic behaviour that changes from one page to the next, or disappears in a private browsing window.

After any update, purge in this order:

rm -rf var/cache/prod/* var/cache/dev/*

Then, under Advanced Parameters > Performance, temporarily switch off the file combination and compression options, clear the Smarty cache, and reload. Those options bundle JavaScript files together and regularly break modules that load their scripts asynchronously.

Check the permissions on var/ as well: a cache that cannot be rewritten produces random symptoms that are very hard to read.

The method for getting back into service

1. Enable debug mode, by creating config/defines_custom.inc.php containing define('_PS_MODE_DEV_', true); rather than editing the core file. Your setting will then survive the next update.
2. Read the logs in var/logs/ and in your host's PHP error log. The name of the missing class or the unknown service points straight at the guilty module.
3. Disable the suspect module in the database, without going through a back office that may be unreachable:

UPDATE ps_module SET active = 0 WHERE name = 'nom_du_module';

4. Clear the cache, check that the site is back, then deal with it properly: update the module with its vendor, or fix the code.
5. Turn debug mode off before you reopen to the public.

Avoiding the next episode

The rule that saves the most time: never update straight on production. A staging environment, a written test plan covering checkout, payments, emails and carriers, and an up-to-date module inventory are enough to turn an outage into a non-event.

For modules built specifically for you, our rules for developing a custom module set out what makes a module survive updates.

Is a module holding your store back?

We get broken modules working again and fix the code when the vendor has stopped keeping up. See our PrestaShop module development service.