502 Bad Gateway

Ce que signifie cette erreur et comment la reconnaître

• Le navigateur affiche 502 Bad Gateway ou Bad Gateway, parfois avec la marque de Nginx, Apache, Cloudflare ou d’un autre proxy.
• L’erreur touche plusieurs utilisateurs, commence après un déploiement ou une modification de configuration, ou apparaît lors d’une augmentation du trafic.
• Les échecs peuvent être intermittents lorsque les workers backend, la mémoire, le CPU ou les connexions à la base de données sont épuisés.
• Le journal du proxy signale un échec de connexion upstream, un délai d’attente, une ligne d’état illisible, une réponse mal formée, des en-têtes trop volumineux ou une erreur de socket.
• Une requête directe vers l’origine fonctionne alors que la même requête via un CDN renvoie 502, ce qui oriente vers un problème d’accès du CDN à l’origine, de pare-feu, de TLS ou de routage.

Causes principales, classées par probabilité

1. Backend arrêté ou instable : PHP-FPM, Node.js, Gunicorn ou un autre processus applicatif est arrêté, redémarre en boucle ou n’a pas démarré après un déploiement.
2. Surcharge ou délai d’attente du backend : les workers, la mémoire, le CPU, les connexions à la base de données ou une autre dépendance sont épuisés ; le proxy ne peut donc pas obtenir une réponse à temps.
3. Configuration upstream incorrecte : le proxy cible le mauvais hôte, port, adresse de conteneur, socket Unix ou chemin d’application.
4. Échec d’accès au socket ou au pare-feu interne : le proxy ne peut pas atteindre le backend en raison de permissions de socket, d’une règle réseau, d’un pare-feu ou d’une modification de security group.
5. Réponse backend invalide ou trop volumineuse : l’application envoie une sortie mal formée, une ligne d’état inexploitable ou des en-têtes plus volumineux que ce que le proxy peut accepter.
6. Échec de la connexion du CDN à l’origine : un CDN ne peut pas joindre l’origine, est bloqué par le pare-feu de l’origine ou ne peut pas établir la connexion HTTPS attendue par sa configuration d’origine.

Comment corriger le problème

1. Identifier l’intermédiaire qui génère le 502

Vérifiez si la page d’erreur porte la marque de Nginx, Apache, Cloudflare, d’une plateforme d’hébergement ou d’un autre intermédiaire. Déterminez si toutes les routes échouent ou si une seule route applicative est concernée, puis notez l’heure de l’échec et l’URL affectée. Vous pourrez ainsi associer la requête aux bons journaux.

2. Vérifier le processus backend et ses journaux

Avec un accès autorisé au serveur ou au panneau d’hébergement, vérifiez que le processus applicatif est en cours d’exécution et accepte des requêtes. Consultez ses journaux pour rechercher des redémarrages en boucle, des erreurs applicatives fatales, un arrêt pour manque de mémoire, des dépendances manquantes ou des échecs au démarrage.

Par exemple, une vérification de service en lecture seule peut être :

systemctl status php8.2-fpm
systemctl status nginx
pm2 status

Utilisez la version installée de PHP-FPM et le gestionnaire de processus réellement utilisés plutôt que de reprendre ces noms tels quels. Si le backend est arrêté ou redémarre en boucle, corrigez d’abord la cause sous-jacente. Envisagez ensuite seulement de redémarrer le service concerné dans le cadre de votre procédure habituelle de changement ; un redémarrage peut interrompre des requêtes et supprimer des informations utiles sur l’état d’exécution. Vérifiez donc l’autorisation nécessaire et collectez auparavant les journaux pertinents.

3. Lire le journal d’erreurs du proxy

Faites correspondre l’horodatage du journal à une requête en échec. Pour Nginx, consultez le journal d’erreurs configuré, généralement /var/log/nginx/error.log. Pour Apache utilisant mod_proxy ou mod_proxy_fcgi, consultez le journal d’erreurs d’Apache.

Voici quelques distinctions utiles :

• connect() failed : le proxy ne peut pas atteindre l’upstream configuré.
• upstream timed out : le backend ou l’une de ses dépendances est trop lent ou surchargé.
• upstream sent too big header : les en-têtes de réponse dépassent la taille des buffers du proxy.
• Une erreur lors de la lecture de la ligne d’état : le backend a fermé la connexion ou renvoyé une réponse invalide.

L’emplacement exact du journal et le format des messages dépendent du serveur et de la plateforme d’hébergement.

4. Vérifier l’hôte, le port ou le socket upstream

Examinez la configuration du reverse proxy. Dans Nginx, vérifiez le bloc proxy_pass ou upstream. Dans Apache, vérifiez ProxyPass, ProxyPassMatch et les paramètres de connexion à PHP-FPM.

Utilisez une vérification en lecture seule des ports à l’écoute et, lorsque cela est pertinent, une requête locale :

ss -tlnp
curl http://127.0.0.1:PORT

Remplacez PORT par le port configuré pour l’application. Si l’application utilise un socket Unix, vérifiez que le chemin existe et que le processus du proxy peut y accéder. Pour PHP-FPM, le paramètre listen du pool doit correspondre à l’adresse ou au socket configuré dans Apache ou Nginx. N’exposez pas publiquement un endpoint de test interne uniquement pour effectuer cette vérification.

5. Examiner la surcharge, les dépendances et les délais d’attente

Si le backend fonctionne mais que les échecs coïncident avec des pics de trafic ou des requêtes lentes, vérifiez le CPU, la mémoire, le nombre de workers, les connexions à la base de données, la profondeur des files d’attente et les limites de ressources du panneau d’hébergement. Un processus peut être actif tout en étant incapable d’accepter du travail supplémentaire.

N’augmentez pas les délais d’attente du proxy ou la taille des buffers sans éléments probants. Si le journal indique des en-têtes trop volumineux, examinez la réponse de l’application et les paramètres Nginx proxy_buffer_size et proxy_buffers concernés. Si une modification de configuration est nécessaire, validez-la et appliquez-la selon la procédure de changement approuvée, plutôt que de recharger un proxy de production sans autorisation.

6. Comparer l’origine et le chemin via le CDN

Lorsque Cloudflare ou un autre CDN est placé devant le site, testez directement l’origine avec l’adresse d’origine et l’en-tête Host appropriés, en disposant de l’autorisation nécessaire. Comparez le résultat avec celui de la requête publique.

• L’origine échoue également : examinez l’application, le proxy, le socket, le port, le pare-feu et les ressources disponibles sur l’origine.
• L’origine fonctionne mais le CDN échoue : vérifiez les règles de pare-feu entre le CDN et l’origine, l’accessibilité de l’origine, le routage et le mode SSL/TLS d’origine du CDN. Confirmez que l’origine présente le protocole et la configuration de certificat attendus par le CDN.

7. Tester à nouveau après correction de la cause

Commencez par confirmer que l’origine renvoie la réponse attendue. Testez ensuite la requête via le reverse proxy ou le CDN. Si seules certaines URL échouent, comparez leurs routes applicatives, la taille des réponses, les exigences d’authentification et les dépendances backend au lieu de considérer le problème comme une panne générale.

8. Vérifier les limites du panneau d’hébergement

Sur cPanel, Plesk ou un hébergement mutualisé similaire, consultez les journaux de PHP-FPM et d’utilisation des ressources. Le compte peut atteindre une limite de processus, de mémoire ou de concurrence imposée par le fournisseur. Si cette limite ne peut pas être modifiée, transmettez à l’hébergeur les heures des échecs, la route concernée et le message de journal pertinent afin qu’il puisse examiner les journaux de l’infrastructure.

Prévention et vérification du correctif

• Exécutez l’application sous la supervision d’un gestionnaire de processus et surveillez les plantages répétés au lieu de compter uniquement sur les redémarrages automatiques.
• Surveillez la mémoire, le CPU, l’utilisation des workers, les connexions à la base de données, la profondeur des files d’attente et les limites du panneau d’hébergement avant qu’ils n’affectent les requêtes.
• Définissez des délais d’attente cohérents et compatibles entre l’application, le proxy, le load balancer et le CDN ; n’utilisez pas des délais plus longs pour dissimuler un backend défaillant.
• Vérifiez le port ou le socket attendu de l’application après les déploiements et les modifications de configuration.
• Testez des routes représentatives directement sur l’origine et via le CDN après toute modification du TLS de l’origine, des règles de pare-feu ou de la configuration du proxy.
• Conservez les journaux du proxy et de l’application avec des horodatages synchronisés afin de pouvoir associer les réponses 502 intermittentes aux événements du backend.
• Documentez le service responsable, l’adresse upstream, les permissions du socket et la procédure de récupération approuvée pour l’environnement.

Questions fréquentes