Erreur 500 : une méthode pour diagnostiquer n'importe quelle application

Le code de statut HTTP 500 (Internal Server Error) indique que le serveur a rencontré une condition inattendue qui l'a empêché de répondre. C'est un message générique, volontairement peu informatif pour ne pas exposer d'informations internes aux visiteurs. La cause réelle est dans les journaux, jamais dans la page d'erreur.

Il faut la distinguer de ses voisines de la famille 5xx : 502 (Bad Gateway) signifie qu'un intermédiaire, comme un reverse proxy, a reçu une réponse invalide du serveur applicatif ; 503 (Service Unavailable) signale une surcharge ou une maintenance ; 504 (Gateway Timeout) indique que le serveur applicatif n'a pas répondu à temps. Chaque code oriente vers un endroit différent.

Une erreur 500 peut être permanente (toutes les pages), intermittente (une requête sur dix), ou ciblée (une seule fonctionnalité, un seul utilisateur). Ce profil est la première information à recueillir : il réduit d'emblée l'espace des causes possibles et oriente la recherche.

Avant de fouiller les journaux, posez les bonnes questions. Depuis quand ? Sur quelles pages ou actions ? Pour tous les utilisateurs ou certains seulement ? Qu'est-ce qui a changé récemment : déploiement, mise à jour d'une extension, changement de configuration, renouvellement de certificat, migration, pic de trafic ?

La question « qu'est-ce qui a changé » résout à elle seule une grande partie des incidents. Consultez l'historique des déploiements, les journaux d'administration, les mises à jour automatiques de l'hébergeur. Si un déploiement récent est en cause, le retour arrière est souvent la première action à envisager, avant même de comprendre.

Reproduisez l'erreur de manière fiable si c'est possible, en notant l'URL, la méthode HTTP, les paramètres et l'heure exacte. Cette précision permet ensuite de retrouver la ligne correspondante dans les journaux parmi des milliers d'autres, et de vérifier la correction.

Commencez par le journal d'erreurs du serveur web (Nginx ou Apache), puis celui du gestionnaire de processus applicatif (PHP-FPM, Gunicorn, uWSGI, PM2, le service systemd de votre application Java ou Node.js), puis le journal de l'application elle-même. Chaque couche ajoute des détails que la précédente n'a pas.

Cherchez d'abord la trace d'exception (stack trace) correspondant à l'horodatage de l'erreur. Elle indique le fichier, la ligne et la chaîne d'appels. Sur PHP, une erreur fatale, une limite de mémoire dépassée ou une extension manquante apparaissent ici. Sur Java ou Node.js, une exception non gérée apparaît avec sa pile complète.

Si les journaux applicatifs sont vides, c'est en soi un indice : le processus ne démarre pas, ou l'erreur survient avant que la journalisation ne soit initialisée (fichier de configuration illisible, variable d'environnement absente, dépendance manquante). Vérifiez alors le journal du service et celui du système (journalctl, dmesg).

Un nombre surprenant d'erreurs 500 n'ont rien à voir avec le code. Un disque plein empêche l'écriture des sessions, des caches et des journaux. Une mémoire saturée conduit le système à tuer des processus. Un certificat ou un jeton expiré fait échouer un appel à un service externe. Une base de données inaccessible ou saturée en connexions bloque toutes les requêtes.

Vérifiez donc l'espace disque, la mémoire, la charge, le nombre de connexions à la base de données et l'accessibilité des services dont dépend l'application (base, cache, file d'attente, API tierces). Vérifiez aussi les permissions de fichiers, souvent modifiées par un déploiement ou une restauration.

Sur les applications conteneurisées, examinez l'état des pods ou conteneurs : redémarrages en boucle, limites de mémoire atteintes, sondes de santé en échec. Un conteneur qui redémarre en permanence produit des erreurs intermittentes très difficiles à comprendre sans cette information.

Lorsque la trace désigne un composant, isolez-le : désactivez l'extension incriminée, contournez le cache, exécutez la requête SQL suspecte directement, appelez l'API tierce manuellement. L'objectif est de confirmer l'hypothèse avec une expérience simple avant de modifier quoi que ce soit.

Sur WordPress et PrestaShop, la méthode classique consiste à activer le mode débogage sur un environnement de test, puis à désactiver les extensions ou modules un par un et à revenir au thème par défaut. Sur une application sur mesure, on reproduit la requête en local avec les mêmes données.

Résistez à la tentation de modifier plusieurs choses à la fois. Un changement, une mesure, puis le suivant. Sinon, vous ne saurez pas ce qui a corrigé le problème, et vous risquez d'en créer un autre sans vous en rendre compte.

La correction doit traiter la cause, pas le symptôme. Augmenter la limite de mémoire de PHP masque une fuite ; redémarrer le service masque une saturation de connexions. Ces mesures sont acceptables pour rétablir le service, à condition de planifier la correction réelle ensuite.

Après correction, vérifiez sur le scénario reproduit, puis surveillez le taux d'erreurs 5xx pendant quelques heures. Une alerte sur ce taux, avec un seuil raisonnable, est la protection la plus simple contre les incidents silencieux : de nombreuses erreurs 500 durent des jours avant qu'un client ne les signale.

Rédigez enfin un compte rendu court : cause, détection, correction, ce qui aurait permis de l'éviter. C'est ce qui transforme un incident en amélioration durable : journalisation plus complète, tests supplémentaires, alerte manquante, procédure de déploiement à corriger.

Si le site est en production et que l'erreur bloque les ventes ou l'activité, le temps compte plus que l'apprentissage. Un intervenant expérimenté reconnaît en quelques minutes les profils d'erreur classiques sur WordPress, PrestaShop, Node.js, Java ou Python, et sait rétablir le service avant de corriger en profondeur.

Faites également appel à un spécialiste si l'erreur est intermittente et que les journaux ne suffisent pas : le diagnostic passe alors par des outils d'observabilité (traces distribuées, profilage), qui demandent de l'outillage et de l'expérience.