Un bug PrestaShop ne se corrige pas en vidant le cache au hasard ou en installant un module « correctif ». Une page blanche, une erreur 500, un panier qui ne se met plus à jour ou une déclinaison indisponible peuvent provenir du thème, d’un module, d’une surcharge, du serveur, d’une mise à jour incomplète ou des données de la boutique. La méthode la plus sûre consiste à rendre l’erreur visible, à la reproduire dans des conditions contrôlées, puis à isoler un seul changement responsable. Elle évite surtout de transformer un incident localisé en panne générale.
Commencer par qualifier précisément le bug
Avant toute manipulation, notez le symptôme observé et les conditions exactes de son apparition. « Le site ne marche plus » n’est pas exploitable ; « une erreur 500 apparaît à la validation du paiement par carte depuis la fiche produit, uniquement pour les visiteurs non connectés » l’est beaucoup plus.
- URL concernée, page du front-office ou écran du back-office ;
- heure approximative du premier incident et fréquence ;
- compte client, produit, combinaison, transporteur ou moyen de paiement utilisé ;
- message affiché, code HTTP et capture d’écran ;
- dernières actions effectuées : mise à jour de PrestaShop, module, thème, PHP, migration ou changement de configuration ;
- navigateurs et appareils touchés.
Reproduisez ensuite le problème dans une fenêtre de navigation privée. Cela élimine les effets d’une session client, d’un cookie obsolète ou d’un cache navigateur. Pour un défaut sur le tunnel de commande, utilisez un produit de test, un transporteur et un paiement de test si votre prestataire le permet. Ne créez pas de commandes réelles uniquement pour diagnostiquer une erreur.
Sécuriser l’intervention avant d’activer le diagnostic
Faites une sauvegarde restaurable des fichiers et de la base de données avant toute correction. Une exportation SQL seule ne suffit pas si le problème est lié à un thème, un module ou une surcharge : il faut aussi pouvoir retrouver les fichiers dans leur état antérieur. Sur une boutique active, préparez une copie de préproduction avec la même version de PHP, les mêmes modules et une base anonymisée lorsque des données clients sont présentes.
Évitez de tester une mise à jour, une désactivation massive de modules ou une modification de table directement en production durant un pic de ventes. Si l’incident empêche toute commande, activez temporairement la maintenance depuis le back-office si celui-ci reste accessible, en autorisant votre adresse IP. Le but est de limiter les commandes incomplètes pendant le diagnostic.
Afficher l’erreur réelle et lire les bons journaux
Une erreur 500 ou une page blanche masque souvent une exception PHP. En environnement de préproduction, activez le mode développement dans le fichier config/defines.inc.php en réglant _PS_MODE_DEV_ sur true. Selon la version et l’environnement, les exceptions sont aussi enregistrées dans les journaux Symfony sous var/logs/, notamment dev.log ou prod.log. Le back-office propose également une vue dans Paramètres avancés > Logs.
Le mode développement ne doit pas rester actif sur une boutique publique : il peut révéler des chemins de fichiers, des requêtes ou des détails techniques. Désactivez-le après le test et conservez le message d’erreur complet dans votre ticket ou votre documentation.
Ne pas se limiter aux logs PrestaShop
Le journal PrestaShop n’enregistre pas tout. Consultez aussi les logs du serveur web (Apache ou Nginx), les erreurs PHP et, selon l’hébergement, les logs PHP-FPM. Filtrez-les sur l’heure exacte de la reproduction. Une erreur telle que Allowed memory size exhausted oriente vers une limite mémoire ou un traitement trop lourd ; Class not found suggère un autoload, un module ou un déploiement incomplet ; une erreur de connexion SQL renvoie plutôt au serveur de base de données ou à ses identifiants.
Dans les outils de développement du navigateur, l’onglet Réseau aide à distinguer un défaut serveur d’un défaut JavaScript. Une requête AJAX qui répond en 500 doit être analysée côté PHP. Une réponse 200 contenant une erreur JavaScript ou un JSON inattendu nécessite plutôt d’examiner le script du thème ou du module concerné.
Isoler méthodiquement le module, le thème ou la surcharge
Les modules sont une source fréquente de régression, particulièrement après une mise à jour de PrestaShop ou de PHP. Désactivez d’abord, sur une préproduction, le dernier module installé ou mis à jour. Testez ensuite le scénario complet, puis réactivez-le pour confirmer la relation de cause à effet. Une correction fiable repose sur ce test de désactivation/réactivation, pas seulement sur une coïncidence.
- Videz le cache depuis Paramètres avancés > Performances.
- Désactivez un seul module suspect dans le gestionnaire de modules.
- Reproduisez exactement le bug, y compris avec le même produit ou la même combinaison.
- Réactivez le module et refaites le test.
- Si le résultat est confirmé, vérifiez une version compatible du module, ses dépendances et son journal.
Si le back-office est inaccessible, n’effacez pas le dossier d’un module actif : PrestaShop peut continuer à tenter de le charger. Une désactivation en base peut dépanner, mais elle exige une sauvegarde et l’utilisation du préfixe réel des tables. Dans ps_module (où ps_ peut être différent), le champ active permet de désactiver un module identifié. Cette action ne remplace pas une analyse de compatibilité et doit être suivie d’un vidage de cache.
Testez aussi le thème. Un thème enfant, une personnalisation Smarty ou un script JavaScript peut casser une fiche produit sans affecter les autres pages. Les surcharges dans le dossier override/ sont également à contrôler : elles peuvent devenir incompatibles après une évolution du cœur. Après toute modification de surcharge, supprimez le cache afin que les classes soient régénérées.
Traiter les cas fréquents selon le symptôme
Erreur 500 ou page blanche
Recherchez d’abord l’exception exacte. Vérifiez ensuite la version de PHP supportée par votre version de PrestaShop et par vos modules, les extensions PHP requises, les droits d’écriture sur var/cache/ et var/logs/, ainsi que l’espace disque disponible. Après un déploiement, contrôlez que les dépendances et fichiers du module ont bien été transférés : un dossier partiellement chargé peut produire une erreur fatale immédiate.
Prix, stock ou déclinaisons incohérents
Sur la fiche produit, vérifiez la combinaison réellement sélectionnée, son impact sur le prix, sa quantité et les règles de prix spécifiques. Videz le cache avant de conclure à une incohérence de données. Si un module de synchronisation ERP, marketplace ou stock intervient, comparez l’heure du dernier import avec l’apparition du bug. Corrigez d’abord la source qui réécrase les données ; modifier manuellement une quantité sera inutile si un cron la remplace quelques minutes plus tard.
Panier ou paiement défaillant
Testez séparément l’ajout au panier, le choix du transporteur et le paiement. Contrôlez les restrictions de pays, devise, groupe client et transporteur. Pour un module de paiement, consultez à la fois son journal et le tableau de bord du prestataire. Une commande marquée en attente côté PrestaShop n’est pas nécessairement perdue : comparez la référence de transaction avant toute relance ou remboursement.
Appliquer une correction durable et vérifier le retour à la normale
Privilégiez la mise à jour compatible du module ou du thème, un correctif fourni par son éditeur, ou une adaptation dans un thème enfant. Ne modifiez pas directement les fichiers du cœur de PrestaShop : la prochaine mise à jour écraserait la correction et compliquerait le support. Documentez chaque changement avec la version concernée, les fichiers modifiés, les commandes exécutées et le résultat du test.
Après le déploiement, videz le cache, désactivez le mode développement et testez les parcours essentiels : affichage d’une catégorie, fiche produit avec déclinaison, ajout au panier, connexion client, création de compte, choix de livraison et paiement. Contrôlez les logs pendant les heures suivantes. Si le bug est lié à une tâche planifiée, vérifiez également son prochain passage et ses éventuelles erreurs : une boutique peut paraître réparée avant qu’un import ou un cron ne réintroduise le problème.
Comment activer le mode debug dans PrestaShop si le back-office est inaccessible ?
Modifiez temporairement la constante _PS_MODE_DEV_ dans config/defines.inc.php pour la définir à true, puis rechargez la page en erreur. Faites-le de préférence sur une préproduction et remettez-la à false après lecture du message, car les détails techniques ne doivent pas être exposés aux visiteurs.
Faut-il vider le cache PrestaShop après chaque modification ?
Oui après une modification de module, de thème, de surcharge, de configuration ou de fichiers Smarty. Utilisez la fonction de vidage de cache du back-office lorsqu’elle est accessible. Le cache ne corrige pas une erreur de code, mais il peut conserver une ancienne classe, un template compilé ou une configuration et fausser le test.
Pourquoi une erreur n’apparaît-elle que pour certains clients ?
Le comportement peut dépendre du groupe client, de la devise, du pays, du transporteur, du contenu du panier, d’une règle de prix ou du cookie de session. Comparez les données du client touché avec un compte de test et reproduisez le cas avec le même produit, la même adresse et le même moyen de livraison.
Peut-on désactiver un module directement en base de données ?
C’est un recours d’urgence lorsque le back-office est indisponible. Après sauvegarde, repérez le module dans la table dont le nom se termine par _module et modifiez son statut actif avec prudence. N’effacez pas son dossier avant sa désactivation, puis videz le cache et recherchez la cause avant de le réactiver.
Quels éléments transmettre à un prestataire pour accélérer un dépannage PrestaShop ?
Transmettez l’URL concernée, l’heure du bug, les étapes de reproduction, les versions de PrestaShop et PHP, les dernières mises à jour, le message d’erreur complet, les extraits de logs pertinents et un accès de préproduction si possible. Évitez d’envoyer des identifiants ou des données clients dans un canal non sécurisé.