Credit : Illustration backtotheweb.fr

Resoudre les erreurs 502 Bad Gateway Nginx

Resoudre les erreurs 502 Bad Gateway Nginx

L'erreur 502 Bad Gateway signifie que Nginx, en tant que reverse proxy, n'arrive pas a obtenir une reponse valide de l'application en amont (PHP-FPM, Node.js, Gunicorn...). Voici comment diagnostiquer et corriger.

Etape 1 : Consulter les logs

La premiere chose a faire est toujours de lire les logs :

# Logs d'erreur Nginx
sudo tail -50 /var/log/nginx/error.log

# Logs specifiques au site
sudo tail -50 /var/log/nginx/monsite.error.log

# Logs PHP-FPM
sudo tail -50 /var/log/php8.2-fpm.log

# Logs systeme
sudo journalctl -u nginx --since "10 minutes ago"
sudo journalctl -u php8.2-fpm --since "10 minutes ago"

Cause 1 : PHP-FPM est arrete ou plante

C'est la cause la plus frequente. Verifiez le statut :

sudo systemctl status php8.2-fpm

# Si arrete, redemarrez
sudo systemctl restart php8.2-fpm

Verifiez que le socket existe :

ls -la /run/php/php8.2-fpm.sock

Si le socket n'existe pas, PHP-FPM a plante. Consultez les logs pour comprendre pourquoi (manque de memoire, erreur fatale PHP...).

Cause 2 : Mauvaise configuration du upstream

Verifiez que Nginx pointe vers le bon socket ou port :

# Configuration socket (recommande)
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}

# OU configuration TCP
location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}

Verifiez que PHP-FPM ecoute sur le meme socket/port :

sudo cat /etc/php/8.2/fpm/pool.d/www.conf | grep listen
# listen = /run/php/php8.2-fpm.sock

Cause 3 : Timeout upstream

Si votre application met trop de temps a repondre, Nginx coupe la connexion. Augmentez les timeouts :

location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_read_timeout 300;
    fastcgi_connect_timeout 60;
    fastcgi_send_timeout 300;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Pour un proxy Node.js :

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_read_timeout 300;
    proxy_connect_timeout 60;
    proxy_send_timeout 300;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Cause 4 : Manque de memoire

PHP-FPM ou Node.js peut etre tue par l'OOM killer :

# Verifier l'OOM killer
sudo dmesg | grep -i "out of memory"
sudo dmesg | grep -i "killed process"

# Memoire disponible
free -h

Attention : vérifiez bien deux fois avant d'appliquer en production.

Si c'est le cas, reduisez le nombre de workers PHP-FPM dans /etc/php/8.2/fpm/pool.d/www.conf :

pm = dynamic
pm.max_children = 10
pm.start_servers = 3
pm.min_spare_servers = 2
pm.max_spare_servers = 5
pm.max_requests = 500

Formule : max_children = RAM disponible / memoire par processus PHP (generalement 30-50 Mo par processus).

Cause 5 : Taille des buffers insuffisante

Si les headers de reponse sont trop grands :

upstream sent too big header while reading response header from upstream

Augmentez les buffers Nginx :

fastcgi_buffer_size 32k;
fastcgi_buffers 8 16k;
fastcgi_busy_buffers_size 32k;

# Pour proxy_pass
proxy_buffer_size 32k;
proxy_buffers 8 16k;
proxy_busy_buffers_size 32k;

Cause 6 : Application Node.js qui plante

# Verifier si le processus tourne
sudo systemctl status monapp

# Voir les logs
sudo journalctl -u monapp -f

# Relancer avec pm2
pm2 restart monapp
pm2 logs monapp

Checklist de resolution rapide

# 1. Verifier les services
sudo systemctl status nginx php8.2-fpm

# 2. Tester la config Nginx
sudo nginx -t

# 3. Verifier les logs
sudo tail -20 /var/log/nginx/error.log

# 4. Verifier la memoire
free -h

# 5. Redemarrer si necessaire
sudo systemctl restart php8.2-fpm nginx

La plupart des erreurs 502 se resolvent en verifiant que le service upstream est bien actif et correctement configure.