Comment corriger l’erreur 502 Bad Gateway dans Nginx (étape par étape)

Une erreur 502 Bad Gateway dans Nginx signifie généralement que Nginx n’a pas pu recevoir de réponse valide d’un serveur en amont, tel que PHP-FPM, Node.js ou une autre application backend.

Les causes les plus courantes sont l’arrêt des services applicatifs, des ports ou sockets en amont incorrects, et des processus backend qui plantent ou ferment les connexions de manière inattendue.

Commencez par consulter les journaux d’erreurs de Nginx. Ils révèlent souvent la raison précise de l’échec de la connexion.

Ce guide présente sept étapes pratiques de dépannage pour les serveurs Linux exécutant Nginx.

Quelles sont les causes d’une erreur 502 Bad Gateway dans Nginx ?

Nginx joue souvent le rôle de proxy inverse : il transmet les requêtes aux applications backend et renvoie leurs réponses aux visiteurs.

Si le service en amont ne répond pas correctement, Nginx peut renvoyer le code de statut HTTP 502.

Les causes courantes comprennent :

• Des services backend arrêtés ou ayant planté.
• Des adresses IP, ports ou sockets Unix en amont incorrects.
• Des défaillances de PHP-FPM ou des processus applicatifs.
• Des problèmes de permissions d’accès aux sockets.
• Une mémoire ou un espace disque insuffisant.
• Des connexions en amont non valides ou fermées prématurément.

Les vérifications suivantes supposent que vous disposez d’un accès SSH et des droits nécessaires pour administrer votre serveur Linux.

1. Consultez les journaux d’erreurs de Nginx

Les journaux d’erreurs de Nginx sont généralement le moyen le plus rapide d’identifier la cause d’une erreur 502.

Connectez-vous à votre serveur via SSH et exécutez :

sudo tail -n 50 /var/log/nginx/error.log

Cette commande affiche les 50 dernières entrées du journal.

Pour suivre les erreurs en temps réel, utilisez :

sudo tail -f /var/log/nginx/error.log

Rechargez la page web concernée et surveillez l’apparition de nouveaux messages.

Selon votre configuration d’hébergement, les journaux peuvent se trouver à un autre emplacement.

Ne modifiez pas les paramètres de Nginx avant d’avoir identifié la cause probable.

2. Vérifiez que le service backend fonctionne

Une erreur 502 survient souvent parce que l’application derrière Nginx s’est arrêtée.

Pour un service applicatif géré par systemd, exécutez :

sudo systemctl status myapp

Remplacez myapp par le nom réel de votre service.

Pour les applications PHP utilisant PHP-FPM, le nom du service peut ressembler à ceci :

sudo systemctl status php8.3-fpm

La version de PHP installée et le nom du service peuvent être différents.

Si le service est en échec, examinez ses journaux :

sudo journalctl -u myapp -n 50

Recherchez les plantages, les dépendances manquantes, les erreurs de configuration ou les défaillances liées à la mémoire.

Ne redémarrez le service qu’après avoir identifié et traité le problème sous-jacent.

3. Vérifiez le port ou le socket en amont

Nginx doit transmettre les requêtes à la bonne adresse backend.

Par exemple, une configuration de proxy inverse peut contenir :

location / {
    proxy_pass http://127.0.0.1:3000;
}

Cette directive indique à Nginx de transmettre les requêtes à une application HTTP qui écoute sur le port 3000.

Vérifiez qu’un processus écoute sur ce port :

sudo ss -ltnp | grep ':3000'

Vous pouvez également tester directement un backend HTTP :

curl -i http://127.0.0.1:3000/

Si le backend n’est pas disponible, examinez la configuration de son service avant de modifier Nginx.

Vérifiez les sockets PHP-FPM

PHP-FPM utilise couramment des sockets Unix ou des ports TCP.

Une configuration Nginx peut contenir :

fastcgi_pass unix:/run/php/php8.3-fpm.sock;

Vérifiez que le socket configuré existe :

ls -l /run/php/

Le chemin du socket doit correspondre au paramètre listen du pool PHP-FPM, et Nginx doit disposer des permissions nécessaires pour s’y connecter.

Important : proxy_pass s’utilise pour les services HTTP en amont, tandis que fastcgi_pass s’utilise pour les services FastCGI comme PHP-FPM. Ces directives ne sont pas interchangeables.

4. Vérifiez la mémoire et l’espace disque du serveur

Les applications backend peuvent planter ou cesser de répondre lorsque le serveur manque de ressources.

Vérifiez la mémoire :

free -h

Vérifiez l’espace disque :

df -h

Vérifiez les processus en cours d’exécution :

top

Si une application a été arrêtée à cause d’un manque de mémoire, vous pouvez trouver des messages pertinents dans le journal système :

sudo journalctl -k --since "1 hour ago"

Recherchez les événements de manque de mémoire ou les messages indiquant l’arrêt de processus.

Si l’espace disque est épuisé, déterminez ce qui l’occupe avant de supprimer des fichiers.

5. Vérifiez les permissions du socket et les journaux de l’application

Il arrive que le backend fonctionne, mais que Nginx ne puisse pas communiquer avec lui.

Pour les sockets Unix, vérifiez le propriétaire et les permissions :

ls -l /run/php/

Vérifiez également les répertoires menant au socket si les journaux signalent une erreur de permission.

Les permissions appropriées dépendent de l’utilisateur des processus de travail Nginx et de la configuration du service backend.

Évitez d’accorder des permissions trop larges, par exemple avec chmod 777. Modifiez plutôt la configuration du service ou du pool concerné afin que les processus autorisés puissent accéder au socket.

Si les journaux d’erreurs indiquent que le service en amont a fermé sa connexion prématurément, examinez les journaux de l’application backend pour rechercher des plantages, des exceptions ou des requêtes ayant échoué.

6. Testez votre configuration Nginx

Des paramètres de proxy incorrects ou des modifications de configuration peuvent également perturber la communication avec le service en amont.

Avant d’appliquer des modifications, validez la configuration Nginx :

sudo nginx -t

Si le test réussit, rechargez Nginx :

sudo systemctl reload nginx

Le rechargement applique les modifications de configuration valides sans redémarrer inutilement le service.

Si le test échoue, corrigez d’abord l’erreur de configuration signalée.

N’augmentez pas les délais d’expiration du proxy ou les limites des tampons à l’aveugle. Ces ajustements ne résoudront pas le problème si le backend est arrêté, si le socket est incorrect ou si la connexion est refusée.

7. Confirmez que l’erreur 502 est corrigée

Après avoir résolu le problème sous-jacent, testez l’URL concernée :

curl -I https://example.com

Remplacez example.com par votre véritable nom de domaine.

Une requête réussie renvoie généralement un statut HTTP approprié, tel que 200 OK, même si les redirections et d’autres réponses valides peuvent produire des codes différents.

Ouvrez également le site web dans votre navigateur et consultez à nouveau les journaux d’erreurs de Nginx.

Si l’erreur réapparaît en cas de forte charge, surveillez le service backend et l’utilisation des ressources tout en reproduisant le problème.

Comment prévenir les erreurs 502 dans Nginx

Toutes les défaillances du backend ne peuvent pas être évitées, mais une bonne administration du serveur réduit les interruptions de service évitables.

• Surveillez l’état de Nginx et du service backend.
• Consultez les journaux de l’application après les déploiements.
• Configurez des stratégies appropriées de rétablissement des services.
• Surveillez l’utilisation de la mémoire, de l’espace de stockage et des connexions.
• Validez les modifications de configuration avant de les appliquer.
• Testez directement les applications avant d’acheminer le trafic via Nginx.

Si une application a besoin de plus de ressources, mesurez son utilisation réelle avant de décider d’augmenter la capacité du serveur.

Questions fréquentes

Conclusion

Pour corriger une erreur 502 Bad Gateway dans Nginx, commencez par déterminer pourquoi l’application en amont ne répond pas correctement.

Consultez d’abord les journaux d’erreurs de Nginx, confirmez que le service backend fonctionne et vérifiez le port ou le socket configuré. Examinez ensuite les limites de ressources, les permissions et les défaillances de l’application.

Dans la plupart des cas, identifier la défaillance précise du service en amont est plus efficace que de redémarrer Nginx à répétition ou de modifier les délais d’expiration.