Dépannage PrestaShop : Écran blanc, erreurs 500 & problèmes courants

L’état d’esprit du dépannage

Quelque chose ne fonctionne plus. L’instinct vous pousse à modifier des paramètres. Résistez. Changer plusieurs choses en même temps rend impossible l’identification de ce qui a résolu le problème. La méthode qui fonctionne : observer, isoler, corriger, vérifier. Lisez l’erreur. Vérifiez les logs. Changez une seule chose. Testez. Répétez.

Avant de toucher à quoi que ce soit, faites une sauvegarde. Dump de la base de données + archive des fichiers. Si votre correctif aggrave la situation, vous aurez besoin d’un moyen de revenir en arrière.

1. Activer le mode debug

Le mode debug est votre premier outil pour chaque problème. PrestaShop masque les erreurs par défaut — c’est bien pour les clients, mais désastreux pour le dépannage.

PrestaShop 1.6 et 1.7

Éditez config/defines.inc.php :

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

Cela active l’affichage des erreurs, désactive le cache Smarty et définit error_reporting sur E_ALL. Sur PS 1.7.7+, cela active également la barre d’outils debug Symfony en bas de chaque page.

PrestaShop 8.x et 9.x

La même approche via defines.inc.php fonctionne, mais PS 8+ lit également le fichier .env :

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

Solution de secours

Si l’erreur survient avant que PrestaShop ne charge sa configuration, forcez l’affichage des erreurs PHP en haut de index.php :

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

Sur PS 1.7.7+, le mode debug active également la barre du profiler Symfony affichant chaque requête en base de données, l’utilisation mémoire, les hits/miss du cache et les templates rendus.

Ne laissez jamais le mode debug activé en production. Il expose les chemins de fichiers, les détails de la base de données et la logique interne à n’importe qui.

2. Écran blanc de la mort (WSOD)

Une page blanche signifie que PHP a rencontré une erreur fatale mais que display_errors est désactivé. L’erreur existe — elle est simplement masquée.

Étape 1 : Vérifier le journal d’erreurs

L’erreur est toujours enregistrée quelque part : var/logs/prod.log (PS 1.7), var/log/prod.log (PS 8+/9), le journal d’erreurs Apache ou le journal d’erreurs PHP. Sur un hébergement mutualisé : ~/logs/error.log.

Étape 2 : Activer le mode debug

Si les logs ne sont pas accessibles, activez _PS_MODE_DEV_ et rechargez la page.

Étape 3 : Vérification via PHP CLI

Si la page est complètement blanche, testez avec PHP : php -l config/defines.inc.php (vérification de syntaxe) ou php -r "require 'config/config.inc.php';" (test de chargement).

Causes les plus fréquentes

• Limite mémoire dépassée : Augmentez dans php.ini : memory_limit = 512M (256M minimum pour PS 1.7+, 512M pour PS 8+).
• Incompatibilité de version PHP : PS 1.6 ne fonctionne plus avec PHP 7.4+. PS 1.7.0-1.7.6 ne fonctionne plus avec PHP 8.0+. PS 9.x nécessite PHP 8.1+.
• Erreur fatale dans un module : Renommez le dossier du module via FTP : modules/problem_module en modules/problem_module_disabled.
• Cache corrompu : Supprimez tout dans var/cache/ (PS 1.7+) ou cache/smarty/compile/ (PS 1.6).
• Override cassé : Renommez temporairement le répertoire override/ pour tester.

3. Erreur 500 Internal Server Error

L’erreur HTTP 500 signifie que le serveur a rencontré une condition qu’il n’a pas pu gérer. Contrairement au WSOD, cela peut même ne pas atteindre PHP.

Problèmes de .htaccess

La cause la plus fréquente. Testez en renommant temporairement : mv .htaccess .htaccess.bak. Si le site se charge (avec des URLs cassées), le .htaccess est en cause.

• mod_rewrite non activé : a2enmod rewrite && systemctl restart apache2
• AllowOverride None : Doit être AllowOverride All dans la configuration du virtual host.
• Directives non supportées : Certains hébergeurs mutualisés bloquent Options ou php_value. Commentez les sections jusqu’à trouver le coupable.
• Régénérer : Shop Parameters → Traffic & SEO → « Generate .htaccess file ».

Permissions des fichiers

Répertoires : 755, fichiers : 644, répertoires accessibles en écriture (var/cache, img, upload) : 775. Jamais 777.

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

Limites PHP

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

max_input_vars est souvent négligé — les pages produit PrestaShop avec des déclinaisons dépassent facilement la valeur par défaut de 1000.

4. Conflits de modules

Les modules sont la source de problèmes la plus courante. Deux modules essayant de faire la même chose entreront en conflit.

La méthode d’isolation

1. Désactivez tous les modules tiers via le gestionnaire de modules.
2. Confirmez que le problème a disparu.
3. Réactivez les modules un par un, en testant après chacun.

Si l’admin est cassé, désactivez via la base de données :

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

Conflits d’overrides

Deux modules ne peuvent pas surcharger la même classe. Vérifiez override/classes/ et override/controllers/. Si vous supprimez un override manuellement, supprimez var/cache/*/class_index.php pour forcer la régénération.

Priorité des hooks

Lorsque deux modules utilisent le même hook, l’ordre d’exécution est important. Ajustez dans Design → Positions, ou interrogez ps_hook_module pour voir l’ordre d’exécution par hook.

Lorsque vous signalez un conflit de module à un développeur, incluez : l’erreur exacte du log, votre version de PrestaShop, la version de PHP, les autres modules actifs et les étapes pour reproduire le problème.

5. Problèmes de cache

PrestaShop dispose de plusieurs caches indépendants. Quand « vider le cache » ne fonctionne pas, vous avez probablement vidé le mauvais.

Les couches de cache

• Smarty : Fichiers TPL compilés dans var/cache/prod/smarty/.
• Symfony : Conteneurs compilés, routes, traductions dans var/cache/prod/.
• OPcache : Bytecode PHP en mémoire partagée — invisible sur le système de fichiers.
• Cache objet : Cache des requêtes en base de données (fichiers ou Redis).
• Cache navigateur : CSS, JS, images sur l’appareil du visiteur.

Tout vider

Panneau d’administration : Advanced Parameters → Performance → Clear cache. Quand l’admin est cassé :

# 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

Après avoir modifié des fichiers PHP, OPcache peut encore servir l’ancienne version. Réinitialisez via une requête web — créez un fichier temporaire contenant opcache_reset();, visitez-le dans un navigateur, puis supprimez-le. La réinitialisation via CLI ne vide que le cache CLI, pas le cache web.

Quand le cache reste « bloqué »

Faites correspondre le cache au changement : template → Smarty, code PHP → OPcache, configuration → Symfony, CSS/JS → navigateur (Ctrl+Shift+R). Vérifiez aussi les permissions de var/cache/, supprimez class_index.php pour forcer la régénération, et purgez le CDN séparément.

Après chaque déploiement : videz le cache Symfony, le cache Smarty, l’OPcache (via le web) et le cache CDN. En oublier un seul donnera l’impression que votre déploiement « n’a pas fonctionné ».

6. Problèmes de base de données

Les problèmes de base de données apparaissent généralement après des mises à jour échouées, des imports interrompus ou des opérations ayant expiré.

Tables corrompues

# 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;

Colonnes manquantes après une mise à jour échouée

Erreur : Unknown column 'new_column' in 'field list'. La mise à jour a été interrompue, laissant les tables incomplètes.

# 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';

Comparer les structures

Installez une copie vierge de votre version de PrestaShop, exportez les deux structures avec mysqldump --no-data, puis comparez-les avec un diff pour révéler les tables, colonnes et index manquants.

Requêtes bloquées

Exécutez SHOW FULL PROCESSLIST pour trouver les requêtes bloquées, KILL <id> pour les terminer, et SHOW ENGINE INNODB STATUS pour vérifier les attentes de verrous.

N’exécutez jamais ALTER TABLE sur de grandes tables de production pendant les heures d’activité. Ajouter une colonne à une table d’un million de lignes peut la verrouiller pendant plusieurs minutes.

7. Problèmes de thème

Templates manquants

Erreur : unable to load template file 'module:modulename/...'. PrestaShop cherche d’abord dans le répertoire de surcharge du thème (themes/your_theme/modules/...), puis dans le module par défaut. Si une surcharge du thème référence un fichier supprimé ou renommé, vous obtenez cette erreur. Sous Linux, les noms de fichiers sont sensibles à la casse.

Erreurs de compilation Smarty

Les balises non fermées (chaque {if} a besoin d’un {/if}), les accolades JavaScript (encadrez le JS dans {literal}{/literal}) et les problèmes d’encodage (les fichiers TPL doivent être en UTF-8 sans BOM) sont les coupables habituels.

Échecs de chargement des assets

Vérifiez la console du navigateur (F12 → Network) pour les erreurs 404. Causes courantes : chemins incorrects dans theme.yml, cache CCC corrompu, mauvaise configuration du CDN.

Problèmes de thème enfant

Thème parent supprimé (le thème enfant échoue avec « Invalid theme »), surcharges de templates obsolètes après des mises à jour du parent, ou fichier theme.yml incomplet dans le thème enfant causant la disparition de modules des hooks.

Lors d’une mise à jour de PrestaShop, consultez le changelog pour les modifications de templates. Les surcharges du thème enfant des templates modifiés doivent être mises à jour.

8. Compatibilité des versions PHP

Matrice de compatibilité

* PS 1.7.8 a un support partiel de PHP 8.0 — le cœur fonctionne mais de nombreux modules ne sont pas compatibles.

Erreurs courantes lors des mises à jour

• PHP 7.x → 8.0 : TypeError: expects string, null given — PHP 8 est strict concernant les valeurs null dans strlen(), strpos(), etc.
• PHP 8.0 → 8.1 : Return type should be compatible — types plus stricts. FILTER_SANITIZE_STRING déprécié.
• PHP 8.1 → 8.2 : Propriétés dynamiques dépréciées.

Important : les versions PHP en CLI et en web peuvent différer sur les serveurs multi-PHP. Vérifiez toujours avec phpinfo() dans un navigateur, et non uniquement avec php -v. Avant de mettre à jour : testez sur un environnement de staging, exécutez php -l sur les fichiers des modules, mettez d’abord les modules à jour.

9. Les emails ne s’envoient pas

• Testez depuis l’admin : Advanced Parameters → Email → « Send a test email ».
• Vérifiez les paramètres SMTP : Hôte, port (587/TLS ou 465/SSL), nom d’utilisateur, mot de passe.
• Vérifiez la table ps_mail : Si les emails y apparaissent, PrestaShop les a envoyés — le problème concerne la délivrabilité.
• PHP mail() : Si cela échoue, passez au SMTP — plus fiable partout.
• Enregistrements DNS : SPF, DKIM, DMARC sont indispensables pour une délivrabilité moderne.

Guide complet : PrestaShop Email Deliverability.

10. Chute soudaine des performances

Diagnostic rapide

Vérifiez l’espace disque (df -h), la charge serveur (uptime), MySQL (SHOW FULL PROCESSLIST) et l’état d’OPcache. Un disque plein fait tout planter silencieusement.

Ralentissements soudains courants

• Mode debug resté actif : Vérifiez _PS_MODE_DEV_ en premier. Cela résout plus de plaintes de « boutique lente » que n’importe quoi d’autre.
• Disque plein : MySQL plante, les caches ne peuvent pas écrire, les logs ne peuvent pas tourner.
• Requête de module défaillante : Une seule requête non indexée sur une grande table peut ajouter des secondes à chaque chargement de page.
• Tâches cron empilées : Plusieurs scripts d’import/indexation s’exécutant simultanément.
• Tables surdimensionnées : ps_connections, ps_log, ps_cart grossissent indéfiniment sans maintenance.

Guide complet : PrestaShop Performance Optimization.

11. Messages d’erreur courants décryptés

« Class 'SomeClass' not found »

Supprimez var/cache/prod/class_index.php (se régénère automatiquement), exécutez composer dump-autoload (PS 1.7+), et vérifiez la casse des noms de fichiers sous Linux. Si un module a été partiellement supprimé, nettoyez les tables ps_hook_module et ps_module.

« CSRF token error » / « Invalid token »

Session expirée (augmentez session.gc_maxlifetime), onglets admin multiples (rafraîchissez la page), proxy inverse supprimant les cookies (excluez l’admin de la mise en cache), ou horloge du serveur décalée.

« Ajax error »

Ouvrez les DevTools (F12) → onglet Network. Reproduisez l’erreur. Trouvez la requête échouée (en rouge, statut 500). L’onglet Response affiche l’erreur PHP réelle.

« Allowed memory size exhausted »

Définissez memory_limit = 512M dans php.ini ou .htaccess. Si la boutique nécessite toujours plus de mémoire, il s’agit d’une fuite mémoire dans un module — utilisez le profiler Symfony pour trouver le coupable.

« Duplicate entry for key »

Violation d’une contrainte d’unicité. Fréquent lors des imports de produits (références en double), installations de modules en multistore, ou lors de la réexécution de mises à jour échouées.

« Deprecated: ... » en cascade

C’est un avertissement, pas une erreur. Pour le masquer : error_reporting = E_ALL & ~E_DEPRECATED. Mieux : mettez le module à jour. Ces avertissements deviennent des erreurs fatales dans la prochaine version de PHP.

12. Récupération d’urgence

Réinitialiser le mot de passe admin

Pour PS 1.6/1.7 (hachage MD5) :

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

Pour PS 8+/9 (bcrypt), téléversez un script PHP temporaire qui inclut config/config.inc.php, utilise PrestaShop\Core\Crypto\Hashing pour générer le hash, met à jour ps_employee, puis supprimez le script immédiatement.

Supprimez le script de réinitialisation immédiatement après utilisation. Quiconque le trouve peut réinitialiser n’importe quel mot de passe administrateur.

Désactiver un module défaillant

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

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

Pour désactiver tous les modules tiers en une fois, mettez à jour ps_module en définissant active = 0 pour toutes les entrées dont le nom ne figure PAS dans la liste des modules natifs de PrestaShop (ps_banner, ps_categorytree, ps_facetedsearch, etc.).

Désactiver les overrides

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

Restaurer depuis une sauvegarde

Mettez le site hors ligne, restaurez la base de données (mysql -u root -p db < backup.sql), restaurez les fichiers, videz tous les caches (rm -rf var/cache/*), réinitialisez l’OPcache, puis vérifiez que la page d’accueil, la page produit, le panier, le tunnel de commande et l’admin fonctionnent tous correctement.

Mode maintenance sans accès 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. Checklist de diagnostic

Imprimez cette liste et suivez-la de haut en bas lorsque quelque chose ne va pas.

Phase 1 : Collecter les informations

• Qu’est-ce qui a changé ? Installation/mise à jour de module, mise à jour de PrestaShop, mise à jour PHP, changement de serveur, modification du thème ?
• Quand exactement cela a-t-il commencé ? Croisez avec les logs de déploiement et les tâches cron.
• Qui est affecté ? Tous les utilisateurs, certains navigateurs, uniquement l’admin, uniquement le front office ?
• Quelle est l’erreur exacte ? Activez le mode debug. Vérifiez la console du navigateur. Vérifiez tous les logs.

Phase 2 : Isoler

• Serveur : espace disque (df -h), mémoire (free -m), CPU (top), MySQL (SHOW PROCESSLIST)
• PHP : version (php -v), vérification de syntaxe (php -l), paramètres (phpinfo())
• Cache : videz toutes les couches — Smarty, Symfony, OPcache, navigateur. Testez en navigation privée.
• Modules : désactivez ceux modifiés récemment. En cas de doute, désactivez tous les modules tiers et réactivez-les un par un.
• Thème : basculez temporairement sur le thème par défaut.
• Base de données : mysqlcheck, journal d’erreurs MySQL, comparez les structures de tables si c’est après une mise à jour.
• Permissions : ls -la sur var/cache, var/logs, img, upload.

Phase 3 : Corriger et vérifier

• Effectuez UN SEUL changement à la fois. Testez. Si cela n’a pas résolu le problème, annulez et essayez le suivant.
• Videz tous les caches après chaque correctif.
• Testez minutieusement : page d’accueil, catégorie, produit, panier, tunnel de commande, admin.
• Testez en navigation privée / dans un autre navigateur.
• Désactivez le mode debug. Supprimez les scripts temporaires.

Phase 4 : Prévenir la récurrence

• Documentez ce qui s’est passé et ce qui a résolu le problème.
• Mettez en place une surveillance : disponibilité, journaux d’erreurs, espace disque.
• Vérifiez que les sauvegardes fonctionnent. Testez une restauration.

Référence rapide

Emplacement des logs

• 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 : selon error_log dans php.ini

Fichiers clés

• config/defines.inc.php — mode debug, bascule des overrides
• app/config/parameters.php — identifiants de BDD, secret (PS 1.7+)
• .env / .env.local — environnement et debug (PS 8+)
• .htaccess — réécriture d’URL, paramètres PHP, sécurité

Commandes CLI essentielles (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

Chaque session de dépannage commence de la même manière : vérifiez l’erreur, vérifiez les logs, isolez la cause. Les développeurs les plus expérimentés ne mémorisent pas chaque erreur — ils savent où chercher. Ce guide vous indique ces emplacements.