Erreurs NGINX et comment les corriger

Lors de l'utilisation de NGINX pour héberger un site web, il arrive que des erreurs perturbent son bon fonctionnement. Ce guide couvre les plus fréquentes — 502 Bad Gateway, 504 Gateway Time-out et 413 Request Entity Too Large — et explique étape par étape comment les résoudre sur un VPS ou un serveur dédié.

502 Bad Gateway

Ce que cela signifie : NGINX ne parvient pas à obtenir de réponse du backend (PHP-FPM, Apache, Node.js, uWSGI, etc.).

Causes les plus fréquentes :

• Le service backend est arrêté ou a planté
• Chemin de socket ou port incorrect dans la configuration
• Permissions incorrectes sur le socket
• Mémoire ou processus worker insuffisants dans PHP-FPM

Comment résoudre :

1. Vérifier le statut de PHP-FPM (ou de votre backend) :

sudo systemctl status php-fpm
# ou pour une version spécifique
sudo systemctl status php8.1-fpm

2. Redémarrer le service :

sudo systemctl restart php-fpm
# ou php8.1-fpm

3. Vérifier le chemin du socket dans les configurations NGINX et PHP-FPM :

   • NGINX : fastcgi_pass unix:/run/php/php8.1-fpm.sock;
   • PHP-FPM (/etc/php/8.1/fpm/pool.d/www.conf) : listen = /run/php/php8.1-fpm.sock

4. Corriger les permissions si nécessaire :

sudo chown www-data:www-data /run/php/php8.1-fpm.sock
sudo chmod 660 /run/php/php8.1-fpm.sock

5. Tester et recharger NGINX :

sudo nginx -t && sudo systemctl reload nginx

504 Gateway Time-out

Ce que cela signifie : NGINX a attendu trop longtemps une réponse du backend et a expiré.
Causes les plus fréquentes :

• Exécution lente d'un script PHP
• Requêtes base de données lentes
• Charge serveur élevée

Comment résoudre :

1. Augmenter les timeouts dans la configuration du site (dans le bloc server ou location) :

proxy_connect_timeout 300s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;
fastcgi_read_timeout 300s;  # pour PHP

2. Optimiser PHP-FPM (dans /etc/php/8.1/fpm/pool.d/www.conf) :

pm.max_children = 50          # augmenter selon les besoins
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20
request_terminate_timeout = 300

3. Redémarrer les services :

sudo systemctl restart php-fpm
sudo systemctl reload nginx

4. Si le problème concerne un script précis — optimisez les requêtes SQL ou ajoutez du cache pour les pages lourdes.

413 Request Entity Too Large

Ce que cela signifie : Le client tente d'envoyer un fichier dont la taille dépasse la limite autorisée par NGINX (1 Mo par défaut).
Causes fréquentes : envoi de fichiers volumineux (photos, vidéos, sauvegardes, archives).

Comment résoudre :

1. Augmenter la limite dans la configuration du site (ou dans /etc/nginx/nginx.conf, bloc http) :

client_max_body_size 64M;  # ou 128M, 512M, 1G, etc.

2. Recharger NGINX :

sudo nginx -t && sudo systemctl reload nginx

3. Augmenter également les limites PHP dans le php.ini (/etc/php/8.1/fpm/php.ini) :

upload_max_filesize = 64M
post_max_size = 64M

Redémarrer PHP-FPM :

sudo systemctl restart php-fpm

Comment recharger NGINX correctement

• Toujours vérifier la configuration en premier :

sudo nginx -t

• Rechargement sans interruption de service :

sudo systemctl reload nginx

ou

sudo nginx -s reload

• Redémarrage complet (uniquement si le rechargement ne suffit pas) :

sudo systemctl restart nginx

Remarques utiles

• Sauvegardez toujours les configurations avant toute modification : sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
• Après chaque modification, vérifiez les logs : /var/log/nginx/error.log et /var/log/nginx/access.log