500 Internal Server Error : causes, journaux et différence avec 502

Pourquoi 500 vous en dit si peu

La RFC 9110 définit 500 comme une condition inattendue qui a empêché le serveur de satisfaire la requête. C'est délibérément large. Tout ce que l'application n'a pas anticipé, d'une référence nulle à une connexion à la base de données échouée en passant par un fichier de configuration qu'elle ne peut pas analyser, finit sous le même numéro.

Ce flou est aussi une mesure de sécurité. Une page 500 ne devrait jamais divulguer publiquement des traces de pile, des chemins de fichiers, des fragments SQL ou des versions de bibliothèques, car ce sont exactement les détails qu'un attaquant recherche. Le code reste donc générique dans la réponse, et le détail va dans un journal que vous seul pouvez lire. Ce compromis est le bon, et il rend une connaissance plus utile que toute autre : où se trouvent vos journaux.

500 contre 502, 503 et 504

Les quatre sont des erreurs serveur, mais elles sont produites par des composants différents et pointent vers des problèmes différents. Bien les distinguer économise la plupart du temps de débogage.

• 500 vient de l'application elle-même. Quelque chose s'est exécuté et a levé une exception. Le journal de l'application contient une trace de pile.
• 502 vient d'un proxy devant l'application, qui a reçu une réponse invalide ou une connexion fermée du backend. Le backend ne journalise souvent rien, car il n'a jamais terminé la requête. Voir le guide du 502.
• 503 est un refus, pas un plantage. Le serveur est surchargé ou en maintenance et refuse du travail délibérément, généralement avec Retry-After.
• 504 est un délai dépassé. Le backend était joignable mais n'a pas répondu dans la limite du proxy. La requête tourne souvent encore en coulisses.

Un raccourci brut : 500 signifie que votre code a cassé, 502 signifie que votre backend est mort ou se comporte mal, 503 signifie que votre serveur dit non délibérément, 504 signifie que votre backend est trop lent. Toute la famille est comparée dans la vue d'ensemble 5xx.

Ce qui cause un 500

• Des exceptions non gérées dans le code de l'application. La plus grande catégorie à elle seule. Une valeur nulle, une conversion de type échouée, un index de tableau hors limites, une division par zéro sur un chemin que personne n'a testé.
• Des échecs de base de données. Pool de connexions épuisé, identifiants renouvelés, la base de données redémarrée, une requête qui fait un interblocage ou expire.
• Des dépendances manquantes ou cassées après un déploiement. Un paquet qui ne s'est pas installé, un fichier que la compilation n'a pas copié, une variable d'environnement qui existe en préproduction mais pas en production.
• Des erreurs de syntaxe de configuration. Sous Apache, une seule directive invalide dans un fichier .htaccess produit un 500 pour chaque requête sous ce répertoire.
• Des permissions et une propriété de fichiers. L'application ne peut pas lire un fichier de configuration ou écrire dans un répertoire de cache, de session ou de téléversement.
• Des limites de ressources. Une limite de mémoire, une limite de temps d'exécution ou un disque plein. Celles-ci produisent typiquement des 500 intermittents qui suivent le trafic.
• Des échecs d'API tierces que le code appelle sans repli, si bien qu'une panne distante devient votre page d'erreur.

Comment diagnostiquer un 500

1. Confirmez le code et qui l'a produit. Une page d'erreur personnalisée peut cacher le vrai statut :

   curl -sS -o /dev/null -D - https://example.com/failing-page

   Vérifiez la ligne de statut et tout en-tête Server ou CDN. Si l'erreur est signée par un réseau de périphérie et que l'origine répond 200, vous ne regardez pas du tout un 500 de votre application.
2. Ouvrez d'abord le journal de l'application. C'est là que se trouve la trace de pile. Journaux du framework, flux de journaux de la plateforme ou stdout du conteneur, selon ce qu'utilise votre pile, et faites correspondre par horodatage et chemin de requête.
3. Puis le journal d'erreur du serveur web. Le error_log d'Apache, le error.log de nginx, ou le journal des événements Windows pour IIS. Si l'application n'a rien journalisé du tout, l'échec s'est produit avant que votre code ne s'exécute, ce qui pointe vers la configuration ou le runtime.
4. Reproduisez-le délibérément. Établissez si le 500 affecte une seule URL, une seule méthode HTTP, un seul utilisateur ou tout le monde. Un 500 seulement sur POST signifie généralement un traitement de formulaire ou un chemin d'écriture. Un 500 pour un seul utilisateur signifie généralement ses propres données.
5. Activez les erreurs détaillées dans un environnement non public. Jamais en production. Reproduisez en préproduction avec la sortie d'erreur complète, ce qui transforme un 500 générique en un numéro de ligne précis.
6. Vérifiez ce qui a changé. Le dernier déploiement, un push de configuration, un renouvellement de certificat, une mise à jour de dépendance ou une migration de base de données. Si le site allait bien il y a une heure, la réponse se trouve presque toujours dans le dernier changement.
7. Vérifiez les ressources de l'hôte. Espace disque, mémoire et nombre de connexions. Un disque rempli de journaux produit des 500 qui semblent totalement sans rapport avec le code.

Les 500 que seule une page renvoie

La plupart des 500 ne mettent pas tout le site hors service. Une route, un formulaire ou une région casse pendant que la page d'accueil continue de se charger, donc rien ne semble anormal depuis l'extérieur et les erreurs remontent des jours plus tard sous forme d'inscriptions perdues. Une vérification HTTP programmée sur les pages qui comptent, pas seulement la page d'accueil, compare le code renvoyé au code attendu et alerte dès qu'une route commence à répondre 500. Les alertes peuvent arriver par e-mail, SMS, appel vocal, Slack, Telegram et bien d'autres canaux, donc une panne nocturne atteint la personne d'astreinte au lieu d'attendre le matin. HostTracker surveille des sites web depuis 2004.