PrestaShop Troubleshooting - Fix White Screens & 500 Errors

The Troubleshooting Mindset

Something broke. The instinct is to start changing things. Resist that. Changing multiple things at once makes it impossible to know what fixed the problem. The method that works: observe, isolate, fix, verify. Read the error. Check the logs. Change one thing. Test. Repeat.

Before touching anything, make a backup. Database dump + file archive. If your fix makes things worse, you need a way back.

1. Enabling Debug Mode

Debug mode is your first tool for every problem. PrestaShop hides errors by default — good for customers, terrible for troubleshooting.

PrestaShop 1.6 and 1.7

Edit config/defines.inc.php:

define('_PS_MODE_DEV_', true);  // Change false to true

This enables error display, disables Smarty cache, and sets error_reporting to E_ALL. On PS 1.7.7+, it also enables the Symfony debug toolbar at the bottom of every page.

PrestaShop 8.x and 9.x

The same defines.inc.php approach works, but PS 8+ also reads from .env:

# .env or .env.local
APP_ENV=dev
APP_DEBUG=1

Emergency Fallback

If the error occurs before PrestaShop loads its config, force PHP error display at the top of index.php:

ini_set('display_errors', 1);
error_reporting(E_ALL);

On PS 1.7.7+, debug mode also enables the Symfony profiler toolbar showing every database query, memory usage, cache hits/misses, and rendered templates.

Never leave debug mode on in production. It exposes file paths, database details, and internal logic to anyone.

2. White Screen of Death (WSOD)

A blank white page means PHP hit a fatal error but display_errors is off. The error exists — it is just hidden.

Step 1: Check the Error Log

The error is always logged somewhere: var/logs/prod.log (PS 1.7), var/log/prod.log (PS 8+/9), Apache error log, or PHP error log. On shared hosting: ~/logs/error.log.

Step 2: Enable Debug Mode

If logs are not accessible, enable _PS_MODE_DEV_ and reload.

Step 3: PHP CLI Check

If the page is completely blank, test with PHP: php -l config/defines.inc.php (syntax check) or php -r "require 'config/config.inc.php';" (load test).

Most Common Causes

• Memory limit exhausted: Increase in php.ini: memory_limit = 512M (256M minimum for PS 1.7+, 512M for PS 8+).
• PHP version mismatch: PS 1.6 breaks on PHP 7.4+. PS 1.7.0-1.7.6 breaks on PHP 8.0+. PS 9.x requires PHP 8.1+.
• Fatal error in a module: Rename the module folder via FTP: modules/problem_module to modules/problem_module_disabled.
• Corrupted cache: Delete everything in var/cache/ (PS 1.7+) or cache/smarty/compile/ (PS 1.6).
• Broken override: Rename the override/ directory temporarily to test.

3. 500 Internal Server Error

HTTP 500 means the server encountered a condition it could not handle. Unlike WSOD, this might not even reach PHP.

.htaccess Issues

The most common cause. Test by temporarily renaming: mv .htaccess .htaccess.bak. If the site loads (with broken URLs), the .htaccess is the problem.

• mod_rewrite not enabled: a2enmod rewrite && systemctl restart apache2
• AllowOverride None: Must be AllowOverride All in the virtual host config.
• Unsupported directives: Some shared hosts block Options or php_value. Comment out sections until you find the culprit.
• Regenerate: Shop Parameters → Traffic & SEO → "Generate .htaccess file".

File Permissions

Directories: 755, files: 644, writable directories (var/cache, img, upload): 775. Never 777.

find /path/to/prestashop -type d -exec chmod 755 {} \;
find /path/to/prestashop -type f -exec chmod 644 {} \;

PHP Limits

memory_limit = 512M
max_execution_time = 300
max_input_vars = 10000
post_max_size = 64M
upload_max_filesize = 64M

max_input_vars is often overlooked — PS product pages with combinations exceed the default 1000.

4. Module Conflicts

Modules are the most common source of problems. Two modules trying to do the same thing will conflict.

The Isolation Method

1. Disable all third-party modules via Module Manager.
2. Confirm the problem is gone.
3. Re-enable modules one at a time, testing after each.

If admin is broken, disable via database:

UPDATE ps_module SET active = 0 WHERE name = 'module_name';
-- Or rename the folder: mv modules/problem_module modules/problem_module.bak

Override Conflicts

Two modules cannot override the same class. Check override/classes/ and override/controllers/. If you remove an override manually, delete var/cache/*/class_index.php to force regeneration.

Hook Priority

When two modules use the same hook, execution order matters. Adjust in Design → Positions, or query ps_hook_module to see execution order per hook.

When reporting a module conflict to a developer, include: the exact error from the log, your PS version, PHP version, other active modules, and steps to reproduce.

5. Cache Problems

PrestaShop has multiple independent caches. When "clear the cache" does not work, you probably cleared the wrong one.

The Cache Layers

• Smarty: Compiled TPL files in var/cache/prod/smarty/.
• Symfony: Compiled containers, routes, translations in var/cache/prod/.
• OPcache: PHP bytecode in shared memory — invisible to the filesystem.
• Object cache: Database query cache (file-based or Redis).
• Browser cache: CSS, JS, images on the visitor's device.

Clearing Everything

Admin panel: Advanced Parameters → Performance → Clear cache. When admin is broken:

# Delete cache directories
rm -rf var/cache/prod/* var/cache/dev/*

# Or use Symfony console (PS 8+/9)
php bin/console cache:clear --env=prod

OPcache

After editing PHP files, OPcache may still serve the old version. Reset via a web request — create a temp file with opcache_reset();, visit it in a browser, delete it. CLI reset only clears CLI cache, not web cache.

When Cache Gets "Stuck"

Match the cache to the change: template → Smarty, PHP code → OPcache, config → Symfony, CSS/JS → browser (Ctrl+Shift+R). Also check var/cache/ permissions, delete class_index.php to force regeneration, and purge CDN separately.

After every deployment: clear Symfony cache, Smarty cache, OPcache (via web), CDN cache. Missing any one makes your deployment appear to have "not worked."

6. Database Issues

Database problems usually surface after failed upgrades, interrupted imports, or timed-out operations.

Corrupted Tables

# Check all tables
mysqlcheck -u root -p prestashop_db --check

# Repair (MyISAM only)
REPAIR TABLE ps_product;

# For InnoDB (most modern installs), rebuild in place:
ALTER TABLE ps_product ENGINE=InnoDB;

Missing Columns After Failed Upgrade

Error: Unknown column 'new_column' in 'field list'. The upgrade was interrupted, leaving tables incomplete.

# Check what columns exist
SHOW CREATE TABLE ps_product\G

# Look for upgrade SQL in install-dev/upgrade/sql/ or install/upgrade/sql/
# Add the missing column manually:
ALTER TABLE ps_product ADD COLUMN `state` TINYINT(1) NOT NULL DEFAULT '1';

Comparing Structures

Install a fresh copy of your PS version, dump both structures with mysqldump --no-data, and diff them to reveal missing tables, columns, and indexes.

Stuck Queries

Run SHOW FULL PROCESSLIST to find stuck queries, KILL <id> to terminate them, and SHOW ENGINE INNODB STATUS to check lock waits.

Never run ALTER TABLE on large production tables during business hours. Adding a column to a million-row table can lock it for minutes.

7. Theme Issues

Missing Templates

Error: unable to load template file 'module:modulename/...'. PrestaShop looks in the theme override first (themes/your_theme/modules/...), then the module default. If a theme override references a deleted or renamed file, you get this error. On Linux, filenames are case-sensitive.

Smarty Compilation Errors

Mismatched tags (every {if} needs {/if}), JavaScript braces (wrap JS in {literal}{/literal}), and encoding issues (TPL files must be UTF-8 without BOM) are the usual culprits.

Asset Loading Failures

Check browser console (F12 → Network) for 404s. Common causes: wrong paths in theme.yml, corrupted CCC cache, CDN misconfiguration.

Child Theme Problems

Parent theme deleted (child fails with "Invalid theme"), stale template overrides after parent updates, or incomplete theme.yml in child theme causing modules to disappear from hooks.

When upgrading PrestaShop, check the changelog for template changes. Child theme overrides of changed templates need updating.

8. PHP Version Compatibility

Compatibility Matrix

* PS 1.7.8 has partial PHP 8.0 support — core works but many modules do not.

Common Upgrade Errors

• PHP 7.x → 8.0: TypeError: expects string, null given — PHP 8 is strict about null in strlen(), strpos(), etc.
• PHP 8.0 → 8.1: Return type should be compatible — stricter types. FILTER_SANITIZE_STRING deprecated.
• PHP 8.1 → 8.2: Dynamic properties deprecated.

Important: CLI and web PHP versions can differ on multi-PHP servers. Always check with phpinfo() in a browser, not just php -v. Before upgrading: test on staging, run php -l on module files, update modules first.

9. Email Not Sending

• Test from admin: Advanced Parameters → Email → "Send a test email."
• Check SMTP settings: Host, port (587/TLS or 465/SSL), username, password.
• Check ps_mail table: If emails appear here, PS sent them — the problem is delivery.
• PHP mail(): If it fails, switch to SMTP — more reliable everywhere.
• DNS records: SPF, DKIM, DMARC are required for modern delivery.

Full guide: PrestaShop Email Deliverability.

10. Performance Suddenly Dropped

Quick Diagnostics

Check disk space (df -h), server load (uptime), MySQL (SHOW FULL PROCESSLIST), and OPcache status. Full disks crash everything silently.

Common Sudden Slowdowns

• Debug mode left on: Check _PS_MODE_DEV_ first. This resolves more "slow store" complaints than anything else.
• Full disk: MySQL crashes, caches cannot write, logs cannot rotate.
• Bad module query: One unindexed query on a large table can add seconds per page load.
• Cron jobs stacking: Multiple import/indexer scripts running simultaneously.
• Bloated tables: ps_connections, ps_log, ps_cart grow endlessly without maintenance.

Full guide: PrestaShop Performance Optimization.

11. Common Error Messages Decoded

"Class 'SomeClass' not found"

Delete var/cache/prod/class_index.php (regenerates automatically), run composer dump-autoload (PS 1.7+), and check case-sensitive filenames on Linux. If a module was partially deleted, clean ps_hook_module and ps_module tables.

"CSRF token error" / "Invalid token"

Session expired (increase session.gc_maxlifetime), multiple admin tabs (refresh), reverse proxy stripping cookies (exclude admin from caching), or server clock wrong.

"Ajax error"

Open DevTools (F12) → Network tab. Reproduce the error. Find the failed request (red, status 500). The Response tab shows the actual PHP error.

"Allowed memory size exhausted"

Set memory_limit = 512M in php.ini or .htaccess. If the store keeps needing more, it is a memory leak in a module — use the Symfony profiler to find the culprit.

"Duplicate entry for key"

A unique constraint violation. Common with product imports (duplicate references), module installs on multistore, or re-running failed upgrades.

"Deprecated: ..." Flood

A warning, not an error. Silence: error_reporting = E_ALL & ~E_DEPRECATED. Better: update the module. These warnings become fatal errors in the next PHP version.

12. Emergency Recovery

Reset Admin Password

For PS 1.6/1.7 (MD5 hashing):

UPDATE ps_employee SET passwd = MD5(CONCAT(
    (SELECT value FROM ps_configuration WHERE name = '_COOKIE_KEY_'),
    'YourNewPassword!'
)) WHERE email = 'admin@yourdomain.com';

For PS 8+/9 (bcrypt), upload a temporary PHP script that requires config/config.inc.php, uses PrestaShop\Core\Crypto\Hashing to generate the hash, updates ps_employee, then delete the script immediately.

Delete the reset script immediately after use. Anyone who finds it can reset any admin password.

Disable a Broken Module

-- Via database
UPDATE ps_module SET active = 0 WHERE name = 'broken_module';

-- Via filesystem (more reliable)
mv modules/broken_module modules/broken_module.disabled

To disable all third-party modules at once, update ps_module setting active = 0 for all entries whose name is NOT in the list of native PS modules (ps_banner, ps_categorytree, ps_facetedsearch, etc.).

Disable Overrides

// config/defines.inc.php
define('_PS_ALLOW_OVERRIDES_', false);

Restore from Backup

Put the site offline, restore database (mysql -u root -p db < backup.sql), restore files, clear all caches (rm -rf var/cache/*), reset OPcache, then verify homepage, product page, cart, checkout, and admin all work.

Maintenance Mode Without Admin

UPDATE ps_configuration SET value = '0' WHERE name = 'PS_SHOP_ENABLE';
UPDATE ps_configuration SET value = 'your.ip' WHERE name = 'PS_MAINTENANCE_IP';

13. Diagnostic Checklist

Print this and work top to bottom when something goes wrong.

Phase 1: Gather Information

• What changed? Module install/update, PS update, PHP update, server change, theme edit?
• When exactly did it start? Cross-reference with deployment logs and cron jobs.
• Who is affected? All users, specific browsers, only admin, only front office?
• What is the exact error? Enable debug mode. Check browser console. Check all logs.

Phase 2: Isolate

• Server: disk space (df -h), memory (free -m), CPU (top), MySQL (SHOW PROCESSLIST)
• PHP: version (php -v), syntax check (php -l), settings (phpinfo())
• Cache: clear all layers — Smarty, Symfony, OPcache, browser. Test in incognito.
• Modules: disable recently changed ones. If unclear, disable all third-party and re-enable one by one.
• Theme: switch to default temporarily.
• Database: mysqlcheck, MySQL error log, compare table structures if post-upgrade.
• Permissions: ls -la on var/cache, var/logs, img, upload.

Phase 3: Fix and Verify

• Make ONE change at a time. Test. If it did not fix it, revert and try the next.
• Clear all caches after every fix.
• Test thoroughly: homepage, category, product, cart, checkout, admin.
• Test in incognito / different browser.
• Disable debug mode. Remove temporary scripts.

Phase 4: Prevent Recurrence

• Document what happened and what fixed it.
• Set up monitoring: uptime, error logs, disk space.
• Verify backups work. Test a restore.

Quick Reference

Log Locations

• PS 1.6: log/ — PS 1.7: var/logs/ — PS 8+/9: var/log/
• Apache: /var/log/apache2/error.log — Nginx: /var/log/nginx/error.log
• MySQL: /var/log/mysql/error.log — PHP: per error_log in php.ini

Key Files

• config/defines.inc.php — debug mode, override toggle
• app/config/parameters.php — DB credentials, secret (PS 1.7+)
• .env / .env.local — environment and debug (PS 8+)
• .htaccess — URL rewriting, PHP settings, security

Essential CLI Commands (PS 1.7+)

php bin/console cache:clear --env=prod
php bin/console prestashop:module list
php bin/console prestashop:module enable module_name
php bin/console prestashop:module disable module_name
composer dump-autoload -o

Every troubleshooting session starts the same way: check the error, check the logs, isolate the cause. The most experienced developers do not memorize every error — they know where to look. This guide gives you those locations.