Déboguer les erreurs HTTP 500 de PrestaShop 9 sans mode de débogage public

Une réponse HTTP 500 indique qu’une requête a échoué sur le serveur. Elle n’identifie pas la couche défaillante et ne justifie pas d’afficher une page de débogage à tous les visiteurs. L’investigation utile la plus rapide commence par circonscrire la requête et corréler des éléments de preuve privés.

Pour une boutique PrestaShop 9, l’échec peut survenir avant l’initialisation de l’application, dans un module, lors du rendu d’un modèle ou après qu’une opération métier a déjà modifié des données. Ces cas exigent des décisions de reprise différentes. Ce processus sépare la sortie d’erreur destinée aux clients des informations nécessaires aux ingénieurs.

Pour les régressions rencontrées lors de l’évaluation d’une version candidate, utilisez le processus de préproduction isolé de RC1 pour reproduire la requête en échec à l’écart des effets secondaires de production.

Délimitez l’incident avant de modifier la configuration

Consignez l’heure du premier échec connu, le nom d’hôte concerné, la méthode de requête, la page ou l’opération et le fait que le problème touche tous les utilisateurs ou un seul scénario. Incluez le dernier déploiement ou changement de configuration, mais traitez-le comme une piste plutôt que comme une cause prouvée.

Demandez-vous si la requête en échec a pu produire un effet secondaire. Réessayer une page produit diffère de répéter l’envoi d’une commande ou une action de traitement logistique. Si la requête a pu valider du travail, examinez l’état obtenu avant de la rejouer.

Conservez une courte fenêtre de preuves autour de l’échec. Les journaux peuvent tourner, les déploiements remplacer les fichiers source et les requêtes répétées masquer la séquence initiale. Copiez uniquement les éléments pertinents dans un espace d’incident à accès restreint conformément à votre procédure opérationnelle.

Évitez de modifier plusieurs choses simultanément. Désactiver des modules, vider tous les caches et redémarrer les services peut modifier temporairement le symptôme tout en empêchant d’en identifier la cause. Chaque intervention doit répondre à une question précise.

Si la boutique est gravement touchée, appliquez la procédure établie de confinement ou de retour arrière tout en conservant les preuves. Le diagnostic et le rétablissement du service peuvent avancer ensemble, mais aucun ne doit dépendre de l’affichage d’exceptions internes aux clients.

Repérez la requête dans les éléments du serveur web

Commencez par le journal d’accès de l’hôte virtuel ou du proxy inverse qui sert réellement la requête. Confirmez l’horodatage, le chemin, la méthode et le statut. Si un proxy intervient, distinguez sa réponse de celle de l’application en amont lorsque les journaux configurés fournissent cette information.

Les chemins des journaux sont propres au déploiement. La documentation Nginx de PrestaShop fournit des exemples d’emplacements de journaux d’accès et d’erreurs, en exigeant explicitement leur adaptation au serveur. Ne supposez pas que ces chemins d’exemple correspondent à votre hôte. Exemple officiel de configuration Nginx.

Trouvez l’entrée correspondante du journal d’erreurs. Un socket en amont absent, un accès refusé à un fichier ou un processus de travail indisponible désignent une autre couche qu’une exception applicative. Une erreur du serveur web peut se produire avant que PrestaShop ait la possibilité d’écrire dans son propre journal.

Pour Apache, examinez la configuration active de l’hôte virtuel et la destination d’erreurs configurée pour l’hôte. Pour les conteneurs, la sortie pertinente peut être collectée sur les flux standard par l’environnement d’exécution plutôt qu’écrite dans un fichier classique de l’hôte.

Gardez les URL et chaînes de requête privées lorsqu’elles contiennent des jetons ou des informations client. Un rapport de support a généralement besoin de la route et des paramètres expurgés, pas de toute la requête brute.

Lisez les journaux PHP-FPM et applicatifs comme des preuves complémentaires

Les erreurs PHP et les exceptions applicatives ne partagent pas nécessairement une destination. Examinez la configuration active du pool FPM, les réglages d’erreur PHP et la configuration des journaux applicatifs plutôt que de deviner un nom de fichier universel.

PHP-FPM propose des commandes de journalisation propres aux pools et un journal des requêtes lentes, mais un journal lent ne remplace pas les preuves d’erreur expliquant un échec fatal. Utilisez chaque source pour la question à laquelle elle répond. Référence de configuration PHP-FPM.

Dans le déploiement PrestaShop, repérez le gestionnaire de journaux Symfony ou applicatif configuré et sa destination propre à l’environnement. Recherchez la première exception pertinente et son contexte précédent. Une exception de rendu ultérieure peut être la conséquence d’un échec antérieur, et non sa cause initiale.

Comparez les contextes d’exécution. Une commande CLI réussie ne prouve pas que le processus web utilise la même version PHP, les mêmes extensions, le même environnement ou les mêmes permissions. Si l’échec ne survient que via HTTP, examinez l’environnement web au lieu de vous fier à php --version depuis le shell d’un administrateur.

Vérifiez la propriété et l’accès des fichiers selon les permissions attendues du compte de service réel. Ne résolvez pas une erreur de permission par des droits d’écriture ouverts à tous. Identifiez le répertoire ou fichier précis et rétablissez la propriété prévue par le déploiement.

Maintenez la journalisation des erreurs active et l’affichage public désactivé

PHP distingue la journalisation des erreurs de leur affichage dans la réponse. Les directives PHP suivantes représentent une intention habituelle en production :

display_errors = Off
display_startup_errors = Off
log_errors = On
error_reporting = E_ALL

Ce sont des directives PHP, et non une configuration PrestaShop complète ou une consigne d’écrasement d’un fichier existant géré par l’hébergeur. Appliquez-les par le mécanisme de configuration pris en charge par le déploiement, confirmez en privé les valeurs effectives de l’environnement web et assurez-vous que la destination des journaux est accessible en écriture et à accès restreint. Référence de configuration des erreurs PHP.

Maintenez également le réglage production/débogage de PrestaShop approprié. Les seuls réglages d’affichage PHP ne garantissent pas qu’une application n’affichera pas sa propre page d’exception de débogage. Utilisez la documentation de configuration du projet et examinez la réponse réelle après un test contrôlé. Référence de configuration PrestaShop.

Ne publiez pas de page phpinfo() pour découvrir la configuration effective. Utilisez les moyens de diagnostic privés de l’hébergeur ou une méthode interne strictement contrôlée, puis supprimez les diagnostics temporaires à la fin de l’investigation.

Journaliser indéfiniment chaque avertissement peut créer du bruit et une pression sur le stockage. Conservez les preuves nécessaires au diagnostic, puis traitez les erreurs répétées et maintenez une rotation normale. La solution n’est pas de cacher l’erreur fatale initiale à l’équipe d’ingénierie.

Corrélez une requête entre les composants

Les horodatages aident, mais un identifiant de requête est plus fiable lorsque plusieurs requêtes surviennent ensemble. Si votre infrastructure génère et propage déjà un identifiant fiable, incluez-le dans les journaux applicatifs et d’intégration.

Ne faites pas aveuglément confiance à un en-tête arbitraire fourni par le client comme identifiant faisant autorité. Validez-le ou remplacez-le à une frontière de confiance et empêchez qu’il contienne des caractères de contrôle susceptibles de corrompre la structure des journaux.

Pour un module que vous maintenez, le contexte de diagnostic structuré peut inclure un identifiant de requête, un identifiant de boutique, un nom d’opération et une classe d’exception. Évitez de journaliser des identifiants secrets, des charges utiles complètes de paiement ou des fiches client entières. L’objectif est de relier les preuves, et non de copier la base de données dans les journaux.

Si la corrélation n’était pas configurée avant l’incident, ne prétendez pas pouvoir la reconstruire parfaitement. Utilisez l’heure, la route, les informations de processus et les identifiants d’entités expurgés pour affiner la correspondance, puis indiquez l’incertitude restante.

Une chronologie d’incident utile distingue l’arrivée de la requête, l’échec applicatif, tout appel externe et la réponse finale. Cela peut révéler le cas critique où une opération s’est terminée mais où la réponse a échoué ensuite.

Reproduisez en privé et modifiez une cause à la fois

Construisez un environnement de reproduction privé avec les mêmes révisions de l’application et des modules et un jeu minimal de données fictives. Préservez la configuration pertinente en isolant les e-mails, paiements et autres effets externes.

Si nécessaire, activez le débogage applicatif détaillé uniquement dans cet environnement restreint. La boutique publique peut continuer à utiliser sa réponse d’erreur normale pendant que les ingénieurs examinent une trace complète en privé.

Pour une exception liée à un module, identifiez la première entrée de pile appartenant à votre code et l’entrée ou dépendance qui ne respecte pas ses attentes. Ne supposez pas que le dernier module cité dans une trace a causé le problème ; il peut simplement être l’appelant ayant rencontré un état non valide.

Appliquez une correction ciblée et réexécutez la séquence initiale. Testez ensuite un cas voisin susceptible de partager la même frontière. Une correction d’une valeur de déclinaison manquante doit inclure un produit avec et sans déclinaison, plutôt qu’un tour sans rapport de toutes les pages du Back Office.

Si le problème ne survient que lors de requêtes concurrentes, préservez cette condition dans la reproduction. Un succès en exécution séquentielle ne réfute pas une condition de concurrence nécessitant des écritures qui se chevauchent.

Une transmission utile au support contient la chronologie expurgée de la requête, la révision concernée, la première exception pertinente et la reproduction minimale. Incluez les éléments vérifiés et écartés, mais distinguez preuves et hypothèses. « Aucune entrée applicative correspondante n’a été trouvée dans cette destination configurée » est plus précis que « l’application n’a rien journalisé ». L’entrée peut être arrivée dans un autre processus ou gestionnaire.

Indiquez aussi si le résultat métier de l’opération initiale est connu. Ce seul fait aide l’ingénieur suivant à décider si une réexécution est sûre ou si un rapprochement doit d’abord avoir lieu.

Vérifiez le rétablissement au niveau métier

Après avoir déployé la correction par le processus habituel, confirmez que l’opération initiale réussit et que de nouveaux échecs correspondants cessent d’apparaître. Vérifiez davantage que le statut HTTP : examinez la commande, la configuration enregistrée ou le résultat d’intégration que la requête devait produire.

Rapprochez les requêtes aux résultats incertains avant de les rejouer. Un HTTP 500 après un paiement ou l’enregistrement d’une commande peut laisser des données métier valides même si le navigateur a vu un échec. La reprise ne doit pas créer de prélèvements ou commandes en double.

Gardez la révision du déploiement et l’heure de vérification dans le dossier d’incident. Si l’erreur revient, ces détails distinguent une correction échouée d’un nouveau problème au symptôme similaire.

Supprimez les modifications temporaires de diagnostic, confirmez que les réponses client n’exposent pas de traces et conservez les preuves minimales nécessaires au support. Rédigez une courte note de cause et de prévention : hypothèse défaillante, déclencheur, correction et test qui la couvre désormais.

Les diagnostics privés ne sont pas moins informatifs que le mode de débogage public. Avec une requête correctement délimitée, une corrélation des journaux et une reproduction contrôlée, ils fournissent de meilleures preuves tout en gardant prévisible le comportement de la boutique en production.

Pour le contexte de la plateforme sous-jacente, consultez notre configuration système requise pour PrestaShop 9 et appliquez les vérifications propres à la version décrites ci-dessus à l’installation que vous évaluez.