PrestaShop 9 upgrade errors: what they mean and how to fix them

The upgrade finished, the Update Assistant said everything went well, and then the store shows a blank page. Or the back office works but checkout does not. Or one module refuses to install. Errors after an upgrade to PrestaShop 9 look different, but most of them come from a short list of causes, and almost all of them can be found in the same way.

This guide is the second half of our PrestaShop 9 upgrade guide. That one explains how to prepare. This one is for when something has already gone wrong, ideally on a staging copy.

First, see the real error#

A blank page or a short "500" message tells you nothing. PrestaShop hides the details on purpose, so you have to turn them on.

• Debug mode. In the back office: Advanced Parameters > Performance > Debug mode. If the back office itself is broken, set _PS_MODE_DEV_ to true in config/defines.inc.php. Turn it off again when you are done, because it shows internal paths to every visitor.
• Log files. PrestaShop writes errors to var/logs/. The newest file there usually names the exact file and line.
• The server's PHP error log. If PrestaShop crashes before it can log anything, the error is in the hosting panel's PHP error log.

Once you see a line like "Call to undefined function" or "Class not found" with a file path, the cause is usually obvious from the path: modules/name/ means a module, override/ means an override, themes/ means the theme.

For the most common messages, such as Call to undefined method Tools::displayPrice() or Class "Swift_Message" not found, we keep a page each with the cause and the fix: PrestaShop 9 errors, one by one.

Clear the cache before anything else#

Many "errors" after an upgrade are only old cache built by the previous version. Delete the contents of var/cache/ (the prod and dev folders) and reload. PrestaShop rebuilds them on the next request. Do the same after every fix below, otherwise you may be looking at an old error that is already solved.

Blank page or error 500 on the front office#

The most common causes, in order:

1. A module that is not ready for the new PHP version. PHP 8 removed old functions such as each() and create_function(), and later versions became stricter with types. One old module that runs on every page is enough to stop the whole store. The log names the module; disable it and check again.
2. An override. Overrides copy parts of old core classes. When the class changes in PrestaShop 9, the override can call methods that no longer exist. To test quickly, use Advanced Parameters > Performance > Disable all overrides. If the page comes back, look in the override/ folder.
3. The theme. Template files changed directly in the theme can call variables or functions that are gone. Switching to the default theme for a moment shows whether the theme is the cause.

A fast way to narrow it down is Disable non built-in modules on the same Performance page. If the store works with only core modules, the problem is one of yours, and you can turn them back on one by one.

A module will not install or enable#

PrestaShop checks which versions a module says it supports. If the module declares a maximum of 8.x, PrestaShop 9 refuses it, even when the code itself would work. The right fix is a PrestaShop 9 version from the author. Editing the version number yourself only hides the warning: the module may still fail on the new Symfony or PHP version, and the next update will overwrite your change.

If the author no longer maintains the module, decide whether it is still needed. If it is, it can be replaced or updated by a developer, but that is real work, not a one-line change.

The back office breaks, but the shop works#

PrestaShop 9 runs on Symfony 6.4, and more back office pages moved from the old controllers to Symfony. Modules that added their own back office pages, forms or services in the old way are the usual cause. Typical signs are an error only on one admin page, a module's settings page that does not open, or a missing menu item. The log shows the module; the fix is its PrestaShop 9 version.

Fields or tabs disappear from product editing#

PrestaShop 9 has only the new product page. Modules that added fields or tabs to the old product page through its hooks no longer show them. The data is still in the database; the module just has no place to display it. A module version built for the new product page brings it back.

Checkout, payment or emails stop working#

These need the most attention, because the store looks fine while orders fail.

• Payment modules are often tied to specific PrestaShop and PHP versions. Test every payment method with a real or sandbox payment and check that the order appears with the correct status.
• Shipping modules that calculate prices from an external service can fail quietly and show no carriers at checkout.
• Order emails may stop if a module changed the templates. Check that the confirmation email arrives, and regenerate the email templates from Design > Email Theme if they look wrong. If the store sends through Microsoft 365 and the test email fails with wrong version number, see PrestaShop and Microsoft 365 email: PrestaShop 9 needs a different encryption setting.

Styles or scripts look broken#

If the store loads but looks broken, the browser is usually loading old combined CSS and JavaScript. Clear the cache, then under Advanced Parameters > Performance save the CCC settings again (or turn them off and on). Also save Shop Parameters > Traffic & SEO once, which rewrites the .htaccess file with the friendly URL rules.

When to stop and roll back#

If checkout or payments fail on the live store and the cause is not clear within an hour, go back to the backup and solve it on a copy. A store that sells on the old version is better than one that does not sell on the new one. This is the main reason to do the upgrade on a staging copy first: every error in this guide is cheap there and expensive on the live store.

Need a hand?#

We upgrade PrestaShop stores to version 9 for a fixed price from €900, always on a copy first, and we fix what breaks along the way. If your store already shows errors after an upgrade, our free readiness check also runs on PrestaShop 9 and lists the modules, theme and overrides that still use removed code. A store health check goes further: it finds the causes and tells you what each fix would cost.