Activer le mode debug de PrestaShop et lire les journaux d'erreurs

Une page blanche, une « erreur 500 », un bouton qui ne fait rien : en production, PrestaShop cache volontairement le détail des erreurs PHP pour ne pas les montrer à vos clients. Pour comprendre ce qui se passe, vous disposez de deux outils complémentaires : le mode debug, qui affiche les erreurs à l'écran, et les journaux (logs), qui les enregistrent dans des fichiers ou en base de données. Ce guide couvre les deux, pour les versions 1.7.8, 8 et 9.

Ce que change réellement le mode debug

Le mode debug tient en une constante PHP, _PS_MODE_DEV_, définie dans le fichier config/defines.inc.php. Quand elle vaut true, PrestaShop :

• affiche les erreurs PHP à l'écran (display_errors activé) et les signale toutes, avertissements compris ;
• affiche aussi les erreurs SQL (constante _PS_DEBUG_SQL_) ;
• fait tourner la partie Symfony (le cadre de développement sur lequel repose une partie du back office) dans l'environnement dev au lieu de prod, avec sa barre de débogage en bas des pages concernées ;
• signale l'état dans l'en-tête du back office par un badge « Debug mode », avec le rappel que toutes les erreurs PHP sont affichées.

Deux conséquences à garder en tête. D'abord, vos visiteurs voient aussi les erreurs, avec des chemins de fichiers et parfois des requêtes SQL : c'est une fuite d'informations sur une boutique en ligne. Ensuite, l'environnement dev est nettement plus lent. Le mode debug s'active donc le temps d'un diagnostic, puis se désactive.

Méthode 1 : depuis le back office

Rendez-vous dans Paramètres avancés > Performances, bloc Mode debug, passez l'interrupteur sur « Oui » et enregistrez.

Le même bloc contient des options utiles pour isoler un problème :

Option	1.7.8	8	9
Désactiver les modules non PrestaShop	oui	non	non
Désactiver tous les overrides	oui	oui	oui
Profileur de débogage (Debug profiler)	non	oui	oui
Mode debug limité à un cookie	non	non	oui

En coulisses, le back office réécrit la ligne define('_PS_MODE_DEV_', …); du fichier de configuration (classe src/Adapter/Debug/DebugMode.php). Il modifie en priorité config/defines_custom.inc.php si ce fichier existe, sinon config/defines.inc.php. Si PHP n'a pas le droit d'écrire dans ce fichier, l'enregistrement échoue avec un message du type « Could not write to file. Make sure that the correct permissions are set on the file… » : dans ce cas, passez par la méthode 2.

Le profileur mérite un mot. Il ne sert pas à afficher les erreurs mais à mesurer : temps d'exécution, mémoire consommée, requêtes SQL, et coût de chaque hook (point d'accroche où les modules s'insèrent) et de chaque module. C'est l'outil à utiliser quand une page est lente plutôt qu'en erreur. Il correspond à la constante _PS_DEBUG_PROFILING_, présente dans les trois versions : en 1.7.8, faute d'interrupteur dans le back office, elle se passe à true dans config/defines.inc.php, comme le mode debug. Comme lui, il s'adresse à tous les visiteurs : à désactiver après usage.

Cette méthode suppose évidemment que le back office fonctionne. Si c'est lui qui affiche l'erreur, utilisez la méthode suivante.

Méthode 2 : modifier le fichier par FTP

Connectez-vous en FTP ou en SSH, ouvrez config/defines.inc.php et repérez, en tête de fichier, la ligne define('_PS_MODE_DEV_', false);. Remplacez false par true pour obtenir :

// config/defines.inc.php
if (!defined('_PS_MODE_DEV_')) {
    define('_PS_MODE_DEV_', true);
}

Enregistrez, puis rechargez la page qui pose problème : le message d'erreur complet doit apparaître.

Deux détails font échouer cette manipulation plus souvent qu'on ne le pense.

Écrivez true, pas 1 ni 'true'. Le fichier teste la valeur avec une comparaison stricte : if (_PS_MODE_DEV_ === true). Avec 1, l'environnement Symfony passe bien en dev, mais l'affichage des erreurs PHP reste désactivé. Vous obtenez un résultat à moitié actif, déroutant.

Vérifiez l'existence de config/defines_custom.inc.php. Ce fichier facultatif est chargé avant defines.inc.php par config/config.inc.php. Comme la constante n'est définie qu'une fois (if (!defined(...))), c'est la valeur du fichier personnalisé qui l'emporte. Si quelqu'un l'a créé un jour, vos modifications dans defines.inc.php n'ont aucun effet. Il a un avantage : il n'est pas remplacé lors d'une mise à jour de PrestaShop, contrairement à defines.inc.php.

PrestaShop 9 : un mode debug visible de vous seul

La version 9 ajoute dans le bloc Mode debug deux champs : nom du cookie et valeur du cookie de débogage. Une fois renseignés, le back office n'écrit plus true mais une condition :

// config/defines.inc.php (ou defines_custom.inc.php) — ligne générée par PrestaShop 9
define('_PS_MODE_DEV_', isset($_COOKIE['debug']) && $_COOKIE['debug'] === 'debug_password');

Ici debug et debug_password sont des exemples : PrestaShop écrit les valeurs que vous avez choisies. Le mode debug n'est alors actif que pour un navigateur qui envoie ce cookie. Pour le créer, ouvrez les outils de développement de votre navigateur (touche F12), onglet Console, sur une page de la boutique :

// Console du navigateur, sur une page de votre boutique
document.cookie = "debug=debug_password; path=/";

Vos clients continuent de voir la boutique normalement pendant que vous lisez les erreurs. La valeur est écrite en clair dans le fichier de configuration : choisissez-en une qui ne se devine pas. Le back office refuse une valeur sans nom de cookie.

Cette option n'existe ni en 1.7 ni en 8 : sur ces versions, aucun mécanisme natif ne limite le mode debug à une adresse IP ou à un navigateur.

Où PrestaShop enregistre les erreurs

Le mode debug montre l'erreur au moment où elle survient. Les journaux, eux, la conservent : c'est souvent là que se trouve l'information quand l'erreur est intermittente ou qu'elle s'est produite chez un client.

Le journal du back office

Paramètres avancés > Logs affiche le contenu de la table ps_log (avec le préfixe par défaut). On y trouve les messages enregistrés par PrestaShop et par les modules via la classe PrestaShopLogger, ainsi que les avertissements et erreurs de la partie Symfony. Chaque ligne indique une gravité, de 1 (information) à 4 (erreur majeure). La page permet aussi de recevoir par e-mail les entrées au-delà d'un niveau de gravité.

Les fichiers du dossier var/logs/

C'est la source la plus détaillée, accessible par FTP. On y trouve deux familles de fichiers.

Les journaux Symfony, dont le nom dépend de l'environnement (prod ou dev) :

Version	Fichier	Rotation
1.7.8	var/logs/prod.log ou dev.log	aucune, le fichier grossit indéfiniment
8 et 9	un fichier par jour, du type prod-2026-10-15.log	30 fichiers conservés par défaut

En production, ces journaux fonctionnent en « déclenchement sur erreur » (fingers crossed) : rien n'est écrit tant que tout va bien, mais dès qu'une erreur survient, tout le déroulé de la requête est enregistré. C'est précieux pour comprendre ce qui a précédé le plantage.

Les journaux d'exceptions : var/logs/AAAAMMJJ_exception.log, par exemple 20261015_exception.log. PrestaShop y écrit chaque exception interne (PrestaShopException), que le mode debug soit actif ou non. C'est le premier fichier à ouvrir après une erreur 500.

Pour lire la fin de ces fichiers en SSH :

# Depuis la racine de la boutique
tail -n 50 var/logs/*_exception.log
grep -iE "critical|error" var/logs/prod*.log | tail -n 30

Le journal du serveur

Certaines erreurs surviennent avant que PrestaShop ait pu charger son propre système de journalisation : erreur de syntaxe dans un override (surcharge d'une classe du cœur), mémoire PHP épuisée, version de PHP incompatible. Elles n'apparaissent alors que dans le journal d'erreurs du serveur (Apache, Nginx ou PHP-FPM), dont l'emplacement dépend de votre hébergement : espace client, panneau Virtualmin, Plesk ou cPanel, ou fichier error_log à la racine du site.

Lire une erreur sans se perdre

Un écran d'erreur ou un journal peut afficher des dizaines de lignes. Concentrez-vous sur trois éléments :

1. La première erreur, pas la dernière : les suivantes sont souvent des conséquences.
2. Le message, à recopier tel quel dans vos recherches.
3. Le fichier et la ligne en cause. Le chemin vous oriente : modules/nom_du_module/ désigne un module, override/ une surcharge, themes/ votre thème, classes/ ou src/ le cœur de PrestaShop. Une erreur dans le cœur est rarement un bogue du cœur : remontez la pile d'appels (stack trace) jusqu'au premier fichier qui appartient à un module ou à une surcharge.

Après le diagnostic

Repassez la constante à false, ou l'interrupteur sur « Non », dès que vous avez relevé l'erreur. Vérifiez que le badge « Debug mode » a disparu de l'en-tête du back office.

Si vous modifiez le fichier par FTP et que rien ne change, la mise en cache du code PHP par le serveur (OPcache) peut retarder la prise en compte du fichier modifié. Le back office, lui, demande l'invalidation de ce cache à chaque bascule. Par FTP, patientez quelques instants ou redémarrez PHP depuis votre panneau d'hébergement.

Pièges connus

• La page reste blanche malgré le mode debug : l'erreur survient avant le chargement de PrestaShop. Consultez le journal du serveur.
• Le mode debug ne s'active pas : valeur différente de true, ou fichier defines_custom.inc.php qui impose une autre valeur.
• var/logs/prod.log énorme en 1.7.8 : sans rotation, il peut atteindre plusieurs gigaoctets. Vous pouvez le vider après l'avoir consulté.
• Mode debug oublié en production : en plus des erreurs visibles, la boutique ralentit. Le badge du back office est là pour vous le rappeler.