502, 504, 413, 403 : décoder les erreurs nginx

Un code d'erreur nginx dit toujours deux choses : qui a échoué, et à quel moment. Les distinguer évite de chercher du mauvais côté pendant une heure.

502 Bad Gateway

nginx a voulu joindre votre application et n'a trouvé personne. Neuf fois sur dix, l'application est simplement arrêtée.

sudo systemctl status mon-appli
sudo ss -tulpn | grep 3000            # quelque chose écoute-t-il ?
curl -I http://127.0.0.1:3000/        # répond-il en direct ?
sudo tail -5 /var/log/nginx/error.log

• connect() failed (111: Connection refused) : rien n'écoute sur ce port.
• connect() failed (113: No route to host) : la machine visée est injoignable — cas d'un proxy_pass vers un autre serveur.
• no live upstreams : tous les serveurs du groupe sont marqués en échec.
• Pour PHP : vérifiez que le chemin du socket dans fastcgi_pass existe vraiment (ls /run/php/).

504 Gateway Timeout

L'application répond, mais trop lentement : nginx a coupé au bout de 60 secondes. Le réflexe est d'augmenter le délai — c'est presque toujours le mauvais.

proxy_read_timeout 300s;   # pour un export ou un import légitime

413 Request Entity Too Large

Un envoi de fichier a dépassé la limite. Elle est réglée à deux endroits, et les deux doivent être relevés.

client_max_body_size 64M;

upload_max_filesize = 64M
post_max_size = 64M

403 Forbidden

nginx a trouvé le fichier mais refuse de le servir. Deux causes : les droits, ou une règle deny.

namei -l /var/www/monsite/index.html    # les droits de tout le chemin, dossier par dossier
sudo -u www-data cat /var/www/monsite/index.html

namei -l est l'outil qu'on oublie : un fichier lisible dans un dossier parent que www-data ne peut pas traverser reste inaccessible, et rien ne le laisse deviner.

404 sur un site qui a des routes

L'accueil marche, les autres pages non : il manque la règle qui renvoie tout à l'application au lieu de chercher un fichier.

location / {
    try_files $uri $uri/ /index.php?$query_string;   # PHP
    # ou, pour une application mono-page :
    # try_files $uri $uri/ /index.html;
}

Le tableau de correspondance