Update Assistant stuck: repairing a PrestaShop 9 upgrade

A failed upgrade leaves the store in an unstable state

The PrestaShop Update Assistant is an excellent tool when everything goes to plan. When it stops halfway, the site ends up with version 9 files and a version 8 database, which produces 500 errors that tell you nothing. So the first rule is simple: never start an upgrade without a backup you have restored and tested.

Below are the failures we see most often on call-outs, with their cause and a way round each one.

"Can't empty cache directory"

This is the most common error on 9.0.x to 9.1.x upgrades, particularly under PHP 8.4.

The module tries to empty var/cache/ and runs into files owned by a different system user, typically because commands were run over SSH under an account other than the web server's.

Workaround:

rm -rf var/cache/prod var/cache/dev
chown -R www-data:www-data var/

Adjust the user to match your hosting. Never delete var/cache itself, only its contents.

"has a dependency on a non-existent service mbo.modules.repository"

This error, which returns an HTTP 500 during the version check step, comes from a Symfony dependency injection container left in an inconsistent state: the MBO module (the built-in marketplace) is declared but its services are never built.

Three steps, in this order:

1. Update the Update Assistant module itself before anything else. An outdated version of the module remains the number one cause of failure.
2. Delete the contents of var/cache/ and check that the app/cache/ directory exists and is writable.
3. Temporarily disable ps_mbo in ps_module, then run the upgrade again.

The process stops without a message

On shared hosting, the Update Assistant runs into three invisible limits: max_execution_time, memory, and the web server's own timeout. The interface just shows a spinner that never stops.

The answer is to go through the command line, which knows nothing about HTTP timeouts:

php modules/autoupgrade/bin/console update:start --config-file-path=config.json

Check first that symlink() is not in the disable_functions list of your PHP configuration: without it, the directory switch fails silently. Set memory_limit to -1 for the duration of the operation.

The trap of finishing the job by hand

When an upgrade fails midway, the temptation is to replay the SQL migration files "by hand". That is a trap.

Those files contain PHP directives wrapped in SQL comments, in the form /* PHP:add_column(...) */. Run them through phpMyAdmin and the comments are ignored: the database structure looks migrated while columns and data are missing. The symptoms surface weeks later, on a rarely used feature.

If the migration fails, restore the backup and start again cleanly. Never patch up a half-applied migration.

The preparation that avoids 80% of failures

Before you start anything:

• Back up files and database, and test the restore on a separate environment.
• Disable every non-native module. A module that crashes during the upgrade phase brings the whole process down. You will re-enable them one at a time afterwards.
• Switch back to the Classic theme for the duration, especially if your theme overrides core templates.
• Check the PHP version. PrestaShop 9 requires PHP 8.1 as a minimum and supports up to 8.4. An upgrade launched on PHP 7.4 will fail every time.
• Check the disk space. The process duplicates the entire site: you need at least twice its current size.
• List the incompatible modules. PrestaShop 9 has dropped Guzzle, League Tactician and Swift Mailer. Any module that depends on them will throw a fatal error once you switch.

After the upgrade: the testing that counts

An upgrade is only "successful" once these points check out:

1. Place an order end to end, real payment included.
2. Confirm that transactional emails arrive, as they are often broken by the move to 9 because the mailing library changed.
3. Check the carriers and the pickup point widgets in the checkout.
4. Regenerate the thumbnails and check that product images display.
5. Read through var/logs/: today's deprecation warnings are the next version's outages.

If moving to version 9 worries you, our article on the end of support for PrestaShop 8 will help you pick the right moment, and our PrestaShop migration page sets out how we work.

Upgrade stuck right now?

We take over interrupted migrations, including when the store is already offline. Free diagnosis, reply within 1 hour, 9am-10pm, 7 days a week.