502 Bad Gateway : ce qui a cassé derrière le proxy et comment le trouver

Qui renvoie un 502 et pourquoi

La RFC 9110 définit 502 pour un serveur agissant comme passerelle ou proxy qui a reçu une réponse invalide d'un serveur en amont auquel il a accédé en essayant de satisfaire la requête. Chaque stack moderne comporte au moins un tel saut : nginx ou Apache devant un serveur d'applications, un répartiteur de charge devant une flotte, un CDN devant votre origine, ou les trois.

Cette stratification est la clé pour lire un 502. Le composant qui a répondu est suffisamment sain pour générer une page d'erreur. Le composant derrière lui ne l'est pas. Donc un 502 sépare toujours votre stack en une moitié qui fonctionne et une moitié cassée, et votre travail est de déterminer où se trouve la frontière.

Ses voisins disent quelque chose de plus précis. Un 504 Gateway Timeout signifie que le backend était joignable mais trop lent. Un 500 signifie que le backend lui-même a tourné et a levé une erreur. Un 502 signifie que le backend a donné une mauvaise réponse ou aucune réponse du tout. La comparaison complète se trouve dans l'aperçu des 5xx.

Causes courantes

• Le processus backend ne tourne pas. Un serveur applicatif qui a planté, un pool PHP-FPM arrêté, un conteneur qui s'est arrêté ou a échoué sa vérification de santé. Le proxy se connecte à un port que personne n'écoute.
• Le backend a planté en cours de requête. Une extinction pour manque de mémoire ou une erreur de segmentation ferme la connexion avant que les en-têtes de réponse ne soient complets.
• Mauvaise adresse ou mauvais port amont. Une config qui pointe vers l'ancien port après un changement, ou vers un hôte qui ne se résout plus.
• Incompatibilité de protocole. Le proxy parle du HTTP simple à un port qui attend du TLS, ou l'inverse. Les octets sont impossibles à analyser, donc le proxy déclare la réponse invalide.
• En-têtes de réponse trop volumineux. Un cookie surdimensionné ou un en-tête inhabituellement long dépasse le tampon du proxy, et la réponse est rejetée plutôt que transmise.
• Incompatibilité keep-alive. Le proxy réutilise une connexion inactive que le backend a déjà fermée, produisant des 502 sporadiques sous une charge par ailleurs normale.
• Redémarrages et déploiements. Toute fenêtre où l'ancien processus s'est arrêté et le nouveau n'accepte pas encore de connexions.
• Tous les backends défaillants. Un répartiteur de charge sans aucun membre valide n'a nulle part où envoyer la requête.

Lire le journal du proxy, ce qui met généralement fin à l'enquête

Le code de statut est générique, mais la ligne de journal du proxy est précise. Avec nginx, voici les messages à savoir reconnaître :

[error] connect() failed (111: Connection refused) while connecting to upstream,
        upstream: "http://127.0.0.1:8080/"

[error] upstream prematurely closed connection while reading response header
        from upstream

[error] recv() failed (104: Connection reset by peer) while reading response
        header from upstream

[error] upstream sent too big header while reading response header from upstream

[error] no live upstreams while connecting to upstream

Chacun pointe quelque part de différent :

• connect() failed (111: Connection refused). Rien n'écoute sur cette adresse et ce port. Le backend est arrêté, lié à une interface différente, ou sur un port différent de ce que dit la config.
• upstream prematurely closed connection. Le backend a accepté la requête puis est mort ou a raccroché avant de terminer la réponse. Cherchez des plantages, des extinctions pour manque de mémoire ou un timeout de worker à l'intérieur de l'application, pas du côté de nginx.
• connection reset by peer. Similaire, mais la connexion a été activement réinitialisée. Souvent un pare-feu entre les deux, ou un backend qui a fermé une connexion poolée que le proxy considérait encore ouverte.
• upstream sent too big header. Un problème de taille de tampon dans le proxy, pas une faute du backend. La réponse est valide mais plus grande que ce que le proxy est configuré pour contenir.
• no live upstreams. Les vérifications de santé ont marqué chaque backend comme en panne.

Comment le corriger

1. Testez le backend directement, en contournant le proxy. Depuis l'hôte du proxy, demandez l'adresse amont elle-même :

   curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/

   Un 200 ici avec un 502 sur l'URL publique signifie que la faute est dans la configuration du proxy ou dans le lien entre les deux. Une connexion refusée signifie que le backend est réellement en panne.
2. Vérifiez que le backend tourne et écoute sur l'adresse attendue par le proxy. Se lier à 127.0.0.1 alors que le proxy compose une adresse de conteneur est une cause fréquente.
3. Lisez le journal d'erreurs du proxy et faites correspondre le message à la liste ci-dessus avant de changer quoi que ce soit à la configuration.
4. Puis lisez le journal du backend. Un plantage, une extinction pour manque de mémoire ou un timeout de worker à la même seconde confirme le cas « prematurely closed ». Le silence pointe plutôt vers la connectivité.
5. Vérifiez l'adresse amont, le port et le schéma dans la config du proxy, surtout après une migration ou une reconstruction de conteneur.
6. Augmentez les tampons d'en-tête du proxy si le journal dit que l'en-tête était trop grand, et découvrez séparément pourquoi l'en-tête a grossi.
7. Faites se chevaucher les déploiements. Démarrez le nouveau processus, attendez qu'il passe une vérification de santé, puis videz et arrêtez l'ancien. Les mises à jour progressives conditionnées par la santé suppriment entièrement la fenêtre de redémarrage qui cause les 502 au moment du déploiement.

Détecter un 502 qui dure vingt secondes

Les 502 au moment du déploiement et en boucle de plantage sont courts. Un backend redémarre, échoue pendant vingt secondes et récupère, donc le temps que quelqu'un vérifie, le site va bien et il ne reste plus rien à examiner. Une vérification HTTP programmée s'exécutant en continu enregistre ces fenêtres avec des horodatages, ce qui transforme « c'était bizarre brièvement ce matin » en un motif que vous pouvez corréler avec les déploiements et les redémarrages. Un 502 peut aussi provenir d'une bordure CDN plutôt que de votre origine, donc vérifier depuis plusieurs régions distingue une panne de backend globale d'un problème de bordure affectant une partie de votre trafic, ce à quoi sert la surveillance de disponibilité distribuée.