PrestaShop Blank Page After Core Update: Recovery Guide

Why Blank Pages Happen After PrestaShop Updates

A blank white page, often called the White Screen of Death (WSOD), is one of the most common and alarming issues PrestaShop store owners face after updating the core software. You initiate an update from 1.7.8.7 to 1.7.8.8, or from 8.1.0 to 8.1.5, the process appears to complete, and then your entire store, both front office and back office, displays nothing but a white screen. No error message, no partial content, just emptiness.

Understanding why this happens requires understanding what a PrestaShop core update does. The update process replaces hundreds of PHP files, modifies database tables, regenerates class indexes, clears caches, and potentially runs migration queries. Any failure at any point in this chain can leave the store in an inconsistent state where PHP encounters a fatal error but has no way to display it because error reporting is disabled in production mode.

The most common causes fall into several categories: incompatible modules that reference removed or changed core classes, PHP version mismatches between the old and new PrestaShop versions, override file conflicts where custom overrides collide with changed core files, insufficient server resources causing the update to terminate mid-process, and database migration failures that leave tables in an inconsistent state.

Step 1: Enable Debug Mode

The very first action when facing a blank page is to make errors visible. PrestaShop suppresses error output in production mode to prevent exposing sensitive information to visitors. You need to temporarily enable debug mode to see what is actually going wrong.

The fastest method is to edit the file /config/defines.inc.php. Look for the line that defines _PS_MODE_DEV_ and change it:

define('_PS_MODE_DEV_', true);

If you cannot access files via FTP or SSH because your hosting panel is also inaccessible, some hosting providers offer a file manager through their control panel (cPanel, Plesk, DirectAdmin) that operates independently of your PrestaShop installation.

In PrestaShop 8.x, you can also enable debug mode through the .env file in the root directory. Change APP_ENV=prod to APP_ENV=dev and set APP_DEBUG=1. This activates the Symfony debug toolbar and detailed error pages.

After enabling debug mode, reload the page. Instead of a blank screen, you should now see a detailed error message with a file path, line number, and stack trace. This error message is the key to diagnosing and fixing the problem.

Step 2: Check Error Logs

If enabling debug mode still shows a blank page (which can happen if the error occurs before PHP even loads the PrestaShop framework), check your server's error logs directly.

On Apache servers, the error log is typically located at /var/log/apache2/error.log or /var/log/httpd/error_log. On Nginx with PHP-FPM, check /var/log/nginx/error.log and /var/log/php-fpm/error.log (or /var/log/php8.1-fpm.log depending on your PHP version). On shared hosting, error logs are usually accessible through the hosting control panel or in a logs directory within your hosting account.

PrestaShop also maintains its own log files in the /var/logs/ directory (PrestaShop 1.7) or /var/log/ directory (PrestaShop 8.x). Look for files named with the current date. These Symfony-based logs can contain detailed information about what went wrong during the update process.

Additionally, check the /log/ directory in your PrestaShop root for any error log files. Some PrestaShop versions write critical errors here when they cannot display them on screen.

Common Cause 1: Incompatible Modules

Modules are the most frequent cause of blank pages after updates. A module that worked perfectly on PrestaShop 1.7.8.7 may crash the entire store on 1.7.8.8 if it uses internal core classes or methods that changed in the update.

The error message typically looks like: Fatal error: Class 'SomeClassName' not found or Fatal error: Call to undefined method ClassName::methodName() or Fatal error: Declaration of ModuleClass::hookMethod() must be compatible with CoreClass::hookMethod().

To fix this, you need to identify and disable the problematic module. If you can access the back office (sometimes only the front office crashes), go to Modules and disable recently installed or updated modules one by one until the problem resolves.

If the back office is also inaccessible, disable modules through the database. Connect to your database using phpMyAdmin or a MySQL client and run:

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

If you do not know which module is causing the problem, you can disable all third-party modules at once by setting their active column to 0. First, identify which modules are third-party by checking the /modules/ directory for non-PrestaShop modules. Then selectively disable them.

A more aggressive approach is to rename the module's directory. For example, rename /modules/somemodule/ to /modules/somemodule_disabled/. PrestaShop cannot load a module whose directory does not match its registered name, effectively disabling it without touching the database.

Common Cause 2: PHP Version Incompatibility

Each PrestaShop version requires a specific PHP version range. PrestaShop 1.7.6 and earlier require PHP 7.1 to 7.3. PrestaShop 1.7.7 to 1.7.8 support PHP 7.2 to 8.0. PrestaShop 8.0 requires PHP 7.2 to 8.1. PrestaShop 8.1 requires PHP 8.0 to 8.2. PrestaShop 9.0 requires PHP 8.1 or higher.

If your hosting environment changed PHP versions during or alongside the PrestaShop update, you may encounter syntax errors or deprecated function calls. Common PHP compatibility errors include: Deprecated: Function create_function() is deprecated (PHP 7.2+ with code written for PHP 5.x), Fatal error: Uncaught Error: Call to undefined function mysql_connect() (PHP 7.0+ removed the mysql extension), and Fatal error: Array and string offset access syntax with curly braces is no longer supported (PHP 8.0+).

Check your current PHP version by looking at the phpinfo() output or running php -v on the command line. If the version is outside the supported range for your PrestaShop version, switch to a compatible PHP version through your hosting control panel.

Common Cause 3: Override Conflicts

PrestaShop's override system allows modules and developers to modify core behavior by placing modified class files in the /override/ directory. During an update, the core classes change, but the override files remain. If an override references a method signature that changed, a property that was removed, or a class that was renamed, the override causes a fatal error.

The class index file at /var/cache/prod/class_index.php (or /cache/class_index.php in older versions) maps class names to their file locations, including overrides. A stale or corrupted class index can load the wrong file for a class, causing immediate crashes.

To test if overrides are the problem, temporarily disable the override system. Edit /config/defines.inc.php and add or modify:

define('_PS_HOST_MODE_', false);

Then delete the class index file to force PrestaShop to regenerate it without overrides. If the store loads after this change, the problem is in one of your override files.

To identify the specific problematic override, look in the /override/classes/ and /override/controllers/ directories. Remove override files one at a time, deleting the class index after each removal, until you find the one causing the crash. Once identified, either update the override to be compatible with the new core version or remove it entirely if it is no longer needed.

Common Cause 4: Cache and Compiled Files

PrestaShop generates compiled Smarty templates, Symfony container caches, class maps, and various other cached files that become invalid after an update. If the update process did not properly clear these caches, the store attempts to use cached files that reference the old code structure.

Clear all caches manually by deleting the contents of these directories (delete the contents, not the directories themselves):

/var/cache/prod/ and /var/cache/dev/ for the Symfony cache. Delete everything inside these directories. PrestaShop will regenerate them on the next page load.

/cache/smarty/compile/ and /cache/smarty/cache/ for Smarty template caches. Stale compiled templates are a very common cause of blank pages after updates.

/var/cache/prod/class_index.php (or /cache/class_index.php) for the class map. This file must be regenerated after any update.

On PHP-FPM setups, also reset OPcache. OPcache stores compiled PHP bytecode in memory, and it may serve the old code even after files have been replaced. Restart the PHP-FPM service, or if you cannot do that, create a small PHP file that calls opcache_reset() and access it through your browser.

Common Cause 5: Database Migration Failures

PrestaShop updates often include database schema changes: new columns, modified indexes, new tables, or data migrations. If the update process was interrupted (timeout, memory limit, connection drop), the database may be in a partially migrated state.

Check the PrestaShop database for the ps_configuration table and look for the PS_VERSION_DB value. If this value does not match the version of the files on disk, the update did not complete properly. PrestaShop may attempt to re-run migrations on the next load, or it may simply fail.

Database migration failures are the most difficult to recover from without a backup. If you have a database backup from before the update, restoring it and re-running the update is often the safest path. If you do not have a backup, you may need to manually apply the missing SQL migration files found in the /install/upgrade/sql/ directory.

Step-by-Step Recovery Procedure

Follow this sequence when recovering from a blank page after a core update. The order matters because each step either fixes the problem or eliminates a possible cause.

Step 1: Enable debug mode in /config/defines.inc.php by setting _PS_MODE_DEV_ to true. Reload the page and read the error message.

Step 2: Delete the contents of /var/cache/prod/, /var/cache/dev/, /cache/smarty/compile/, and /cache/smarty/cache/. Delete class_index.php. Reload the page.

Step 3: If the error points to a specific module, disable that module by renaming its directory or setting active = 0 in the ps_module database table. Reload the page.

Step 4: If the error points to an override file, move the contents of the /override/ directory to a temporary backup location. Delete class_index.php again. Reload the page.

Step 5: Verify that your PHP version is compatible with the PrestaShop version you updated to. Check phpinfo() or php -v. Switch PHP versions if needed.

Step 6: Check file permissions. The update process may have created files with incorrect ownership. All PrestaShop files should be readable by the web server user, and the /var/, /cache/, /img/, /upload/, /download/, /translations/, /themes/, and /modules/ directories should be writable.

Step 7: If none of the above resolves the issue and you have a database backup, restore the database and files from backup, then attempt the update again after addressing any issues you identified during the diagnosis.

Safe Update Procedure for Future Updates

Prevention is far better than recovery. Follow this procedure for every PrestaShop core update to minimize the risk of blank pages and data loss.

Before the update: Create a complete backup of both the database and all files. Not just the database, not just the files, but both. Store these backups in a location outside your hosting account if possible. Test that you can actually restore from these backups before proceeding.

Disable all third-party modules. This is the single most effective step you can take to prevent blank pages. Core modules (those that ship with PrestaShop) are designed to be compatible with the update, but third-party modules are not guaranteed to be. Disable them before the update and re-enable them one by one afterward, testing the store after each re-activation.

Disable the override system. If you have custom overrides, disable them before the update. Re-evaluate each override after the update to determine if it is still compatible and still necessary.

Check the release notes. Every PrestaShop release includes notes about compatibility requirements, known issues, and breaking changes. Read them before updating, not after something breaks.

Put the store in maintenance mode. This prevents customers from placing orders during the update and encountering errors. Navigate to Shop Parameters, General, Maintenance in the back office and enable maintenance mode.

During the update: Monitor the update process. Do not close the browser tab or navigate away. If the update takes longer than expected, check your server error logs for timeout or memory errors. If the process appears stuck, wait at least 10 minutes before taking any action, as large stores may have significant database migrations to process.

After the update: Clear all caches. Verify that the back office loads correctly. Check the front office. Re-enable modules one by one, checking the store after each one. Re-enable overrides one by one if applicable. Disable maintenance mode. Monitor error logs for the next 24 hours.

Rollback Strategies

When recovery is not possible or too time-consuming, rolling back to the previous version may be the best option. However, PrestaShop does not have a built-in rollback mechanism, so you need to plan for this possibility before starting the update.

Full rollback from backup: Restore both the database and files from your pre-update backup. This is the cleanest approach but requires that you made a complete backup before the update. After restoring, verify that the store functions correctly and that no orders or customer data created during the failed update period are lost (if the store was in maintenance mode, nothing should have changed).

Partial file rollback: If only the files are corrupted but the database is fine, you can replace the PrestaShop files with the previous version while keeping the current database. Download the exact previous version of PrestaShop from the official release archive, extract it, and overwrite the files on your server. Keep your custom modules, themes, and configuration files. This approach is risky because the database may have been partially migrated, creating an inconsistency between the files and the database schema.

Forward fix: Sometimes the fastest path is not to roll back but to fix the specific error. If the error is caused by a single incompatible module or override, fixing or removing that one component may take minutes compared to hours for a full rollback. This approach is best when you have clearly identified the cause from the error message.

The Importance of Database Backups

Every section of this guide mentions backups, and for good reason. A PrestaShop database contains every product, every order, every customer account, every configuration setting, and every piece of content in your store. Losing it means losing your business data.

Automated daily backups are not optional for a production PrestaShop store. Configure your hosting provider's backup system, use a database backup module, or set up a cron job that runs mysqldump at regular intervals. Store backups in multiple locations. Test your restore procedure periodically to ensure backups are actually usable.

Before any update, create a manual backup in addition to your automated backups. Name it clearly with the date and the PrestaShop version, so you can identify it immediately if you need to restore.

When to Seek Professional Help

If you have followed all the steps in this guide and still face a blank page, or if the error messages point to deep core issues that require code-level fixes, it may be time to engage a PrestaShop developer. Provide them with the error messages you collected, the PrestaShop versions involved (before and after the update), your PHP version, and any actions you have already taken. This information will significantly reduce the time needed to diagnose and resolve the issue.

Attempting to manually edit core PrestaShop files without understanding the framework architecture can create additional problems. If the error message references Symfony containers, dependency injection, or kernel configuration, these are areas where incorrect changes can cascade into multiple failures.

For more details, read our guides: Debugging PrestaShop: The Complete Developer Toolkit and PrestaShop 1.7 vs 8 vs 9: Which Version Should You Be Running?.