Erreurs HTTP 500 dans PrestaShop 9 : débogage sûr en production
Une réponse HTTP 500 indique qu’une requête a échoué, mais pas pourquoi. Dans une boutique PrestaShop, le symptôme visible peut provenir d’une exception de module, d’un problème de modèle, d’une défaillance de base de données, d’une erreur fatale PHP, de ressources épuisées ou d’un événement survenu avant la fin du démarrage de PrestaShop.
La pire réaction consiste à activer le mode débogage complet sur une boutique de production fréquentée et à le laisser activé en attendant que l’erreur se reproduise. La sortie de débogage peut révéler aux visiteurs les chemins de fichiers, les traces d’appels et d’autres détails d’implémentation, alors qu’une panne intermittente peut encore disparaître avant que quelqu’un voie le message utile.
Une meilleure démarche consiste à maintenir la boutique en mode de production normal, à recueillir assez de contexte pour identifier la requête défaillante et à utiliser les éléments disponibles au niveau du serveur ou de l’application pour préciser la cause. Ce guide présente une méthode pratique pour PrestaShop 9.
1. Traiter HTTP 500 comme un symptôme, pas comme un diagnostic
Commencez par décrire précisément où la panne apparaît. Une interruption de toute la boutique diffère d’une page produit qui échoue uniquement avec une déclinaison particulière, et une exception dans le back-office après l’enregistrement d’un produit diffère d’un échec du paiement côté boutique.
Consignez :
- l’URL ou la route exacte ;
- si la panne concerne la boutique, le back-office ou une requête API ;
- l’heure approximative ;
- l’action immédiatement antérieure à l’erreur ;
- si la requête échoue systématiquement ou seulement occasionnellement ;
- si le problème a commencé après une mise à jour d’un module, du thème, de PHP ou de PrestaShop ;
- si une seule boutique est touchée dans une installation multiboutique.
Ce contexte réduit le périmètre de recherche avant toute modification de configuration.
2. Ne pas utiliser le mode débogage de production comme système de surveillance
Le mode débogage de PrestaShop est utile dans un environnement contrôlé de développement ou de préproduction, car il rend les exceptions immédiatement visibles. Il ne remplace pas la capture des erreurs en production.
Sur une boutique en ligne, laisser le mode débogage activé peut modifier ce que voient les clients et révéler des informations techniques. Cela ne résout pas non plus les pannes intermittentes : si l’erreur survient une seule fois à 03:00 sans observateur, les éléments utiles peuvent malgré tout être perdus.
Utilisez le mode débogage complet lorsque vous pouvez reproduire le problème sans risque en préproduction ou pendant une fenêtre de maintenance contrôlée. Pour l’exploitation courante en production, privilégiez les journaux et une capture diagnostique qui reste sûre en cas de panne.
3. Déterminer si PrestaShop a eu le temps de traiter la requête
La première distinction importante consiste à déterminer si la panne s’est produite dans l’application PrestaShop/PHP en cours d’exécution ou avant que cet environnement soit disponible.
Les diagnostics au niveau de l’application peuvent généralement aider pour les défaillances suivantes :
- exceptions Symfony ;
- exceptions de contrôleur ou de module ;
- exceptions de modèle ;
- exceptions de base de données qui se propagent dans l’application ;
- erreurs fatales PHP survenant après l’enregistrement de l’environnement d’exécution concerné et des gestionnaires d’arrêt.
Ils peuvent ne pas voir les pannes causées par le serveur web, la terminaison TLS, un plantage brutal de PHP-FPM, l’arrêt d’un processus par le système d’exploitation faute de mémoire, un proxy inverse ou un processus qui meurt avant le démarrage de l’application.
Si aucun incident applicatif n’existe à l’heure d’une réponse 500 connue, ne supposez pas que l’outil de capture a échoué. Vérifiez le journal d’erreurs du serveur web, le journal PHP-FPM et le panneau de contrôle de l’hébergement au même horodatage.
4. Capturer le contexte de la requête avant de tenter des corrections au hasard
Un incident utile doit fournir plus que « PHP a échoué ». Recueillez assez d’informations pour relier la panne à une véritable requête :
- le type d’exception ou d’erreur ;
- un message expurgé des données sensibles ;
- le fichier et la ligne ;
- une trace d’appels sans données sensibles ;
- la route et le contrôleur ;
- le contexte de la requête ;
- l’identifiant de boutique lorsqu’il est disponible ;
- les versions de PrestaShop et de PHP ;
- le contexte du thème et des modules lorsqu’il est disponible ;
- l’utilisation mémoire et le temps d’exécution lorsqu’ils sont disponibles.
Ne collectez pas les mots de passe, les en-têtes d’autorisation, les cookies ou les corps bruts de requêtes simplement parce qu’ils sont techniquement accessibles. Les diagnostics de production doivent être utiles sans devenir un second dépôt de données clients sensibles.
5. Distinguer un incident isolé d’un problème récurrent
Une panne unique peut provenir d’une dépendance temporairement indisponible ou d’une requête inhabituelle. Une panne répétée présentant la même signature stable mérite une priorité différente.
Regroupez les incidents répétés selon des caractéristiques stables : classe d’erreur, message normalisé, fichier et cadre d’appel utile. Suivez ensuite la fréquence de la panne et les dates de sa première et de sa dernière apparition.
Cela transforme un flux bruyant d’erreurs individuelles en questions exploitables :
- Cette erreur s’est-elle produite une fois ou 500 fois ?
- A-t-elle commencé immédiatement après un déploiement ?
- Ne touche-t-elle qu’une seule route ?
- N’apparaît-elle que dans une boutique ?
- La même erreur se produit-elle encore après une correction ?
6. Reproduire seulement après avoir recueilli des éléments
Une fois le message, l’emplacement et le contexte de la requête disponibles, tentez de reproduire la panne dans l’environnement le plus sûr à votre disposition.
Si l’incident désigne une page produit, reproduisez-le avec le même produit et la déclinaison concernée. S’il désigne une action d’enregistrement administrative, utilisez le même parcours dans le back-office. S’il apparaît pendant la commande, reproduisez-le avec un client de test et un parcours de paiement de test approuvé plutôt que d’expérimenter sur une véritable commande.
Pour les erreurs liées à une mise à niveau, comparez le parcours défaillant avec le processus de préproduction décrit dans notre guide de mise à niveau de PrestaShop 8 vers 9.
7. Lire le premier cadre d’appel utile, pas seulement la page finale d’exception
Une trace d’appels est surtout utile lorsqu’on la lit comme une succession d’appels, plutôt que comme une accumulation de chemins de fichiers. L’exception de niveau supérieur peut être levée par Symfony, tandis que le premier cadre propre au projet désigne un service de module, un modèle ou une surcharge personnalisée intervenus plus tôt.
Recherchez :
- un répertoire ou un espace de noms de module ;
- un modèle du thème impliqué dans le rendu ;
- une requête de base de données ou un appel de dépôt proche de la panne ;
- une action de contrôleur qui précise le parcours touché ;
- un chemin de code récemment introduit par une mise à jour.
N’accusez pas automatiquement le premier nom de fichier tiers que vous voyez. Des appels du framework et des modules peuvent figurer dans la même trace même lorsque la cause sous-jacente est une donnée invalide ou une dépendance défaillante.
8. Utiliser Crash Snapshot Lite pour recueillir des éléments applicatifs sans risque en production
Crash Snapshot Lite est le module gratuit de PrestaSuite conçu pour ce parcours de production précis. Il vise à capturer les défaillances prises en charge de l’application PrestaShop/PHP tout en maintenant la boutique en mode normal.
Son fonctionnement Lite comprend la capture des exceptions, celle des erreurs fatales et des arrêts après l’enregistrement de l’environnement d’exécution, les codes d’incident, les messages et traces expurgés des données sensibles, le contexte de base de l’environnement, le regroupement par empreinte, le nombre d’occurrences et un tableau de bord des incidents.
Les incidents fatals ou d’arrêt utilisent une file d’attente privée sur disque : le module ne dépend donc pas d’une connexion saine à la base de données au moment exact d’une erreur fatale. Une tâche cron privée de maintenance peut importer les entrées en attente et effectuer le nettoyage lié à la durée de conservation.
Crash Snapshot Lite se limite volontairement au niveau applicatif. Il ne peut pas remplacer les journaux du serveur et de PHP-FPM pour les pannes survenant avant PrestaShop ou hors du processus PHP.
Consultez la documentation de PrestaSuite pour l’installation, l’autotest et la maintenance.
9. Relier l’incident à un changement récent sans deviner
Lorsqu’une erreur apparaît après un déploiement, comparez les faits avant d’annuler des changements sans rapport. Comparez l’horodatage de la première occurrence avec :
- les mises à jour de modules ;
- les mises à jour du thème ;
- les mises à jour de PrestaShop ;
- les changements de version PHP ;
- les changements du schéma de base de données ;
- les changements de configuration ;
- les nouvelles tâches cron ou d’importation.
Une concordance temporelle constitue un indice utile, mais pas une preuve. Confirmez le changement suspecté en reproduisant le parcours défaillant ou en testant un retour arrière sûr en préproduction.
10. Conserver une stratégie de diagnostic de production à deux niveaux
Aucun outil ne voit toutes les pannes. Une installation PrestaShop de production pratique conserve deux niveaux d’éléments diagnostiques :
- les diagnostics applicatifs pour les exceptions, erreurs fatales, routes et incidents regroupés ;
- les journaux du serveur et de l’environnement d’exécution pour les pannes antérieures au démarrage de l’application, les réponses 502/503 en amont, les plantages PHP-FPM, les arrêts pour manque de ressources et les événements d’infrastructure.
Cette distinction évite de perdre du temps. Si l’application a capturé l’incident, examinez d’abord ses éléments. Si la requête a échoué alors qu’aucun environnement applicatif n’existait, passez directement au niveau serveur.
Liste de contrôle HTTP 500 en production
- Laissez le mode débogage de production désactivé.
- Consignez la route exacte, l’horodatage et l’action de l’utilisateur.
- Vérifiez si la panne est reproductible.
- Examinez les incidents au niveau applicatif.
- Consultez les journaux serveur/PHP lorsqu’aucun incident applicatif n’existe.
- Regroupez les pannes répétées plutôt que de traiter chaque occurrence comme unique.
- Reproduisez en préproduction avec le même parcours.
- Refaites les tests après la correction et vérifiez l’arrêt des nouvelles occurrences.
Questions fréquentes
Dois-je activer le mode débogage lorsqu’un client signale une erreur 500 ?
Pas comme première réaction en production. Recueillez d’abord l’horodatage, la route et les journaux disponibles ou l’incident capturé. Utilisez le mode débogage pendant une reproduction contrôlée lorsqu’il est sûr d’exposer les informations diagnostiques.
Un module PrestaShop peut-il capturer toutes les erreurs HTTP 500 ?
Non. La capture au niveau applicatif ne fonctionne qu’une fois l’environnement PHP et PrestaShop concerné disponible. Les pannes du serveur web, les plantages brutaux de processus et les défaillances d’infrastructure nécessitent des journaux côté serveur.
Pourquoi la même erreur n’apparaît-elle que parfois ?
Les données déclenchantes, la route, l’état du client, la déclinaison, l’état du cache, une tâche en arrière-plan ou les ressources disponibles peuvent varier entre les requêtes. C’est pourquoi le contexte de requête et l’historique regroupé des occurrences sont plus utiles qu’une capture d’écran isolée.
Que vérifier après avoir corrigé l’erreur ?
Répétez le parcours d’origine, surveillez les nouvelles occurrences de la même empreinte et examinez les journaux serveur pertinents. Une correction est plus convaincante lorsque le parcours initialement défaillant réussit et que l’incident cesse de se reproduire.