Dépannage des erreurs courantes de Nginx : Un guide pratique

Le dépannage des erreurs courantes de Nginx devient beaucoup plus facile lorsque vous cessez de considérer le code d'état comme le problème entier. Un 502 peut être une application plantée, un mauvais chemin de socket, ou un backend qui a renvoyé des en-têtes cassés. Un 403 peut être dû à des permissions de fichier, un fichier d'index manquant, ou une règle de refus qui a correspondu à plus que ce que vous attendiez.

Commencez par les preuves : le journal des erreurs, le journal d'accès, nginx -t, et les journaux du backend si Nginx sert de proxy vers une application. Deviner à partir de la page du navigateur seul fait perdre du temps.

Commencez par les vérifications rapides

Exécutez ces commandes avant de modifier la configuration :

sudo nginx -t
sudo systemctl status nginx --no-pager
sudo tail -n 80 /var/log/nginx/error.log
sudo tail -n 80 /var/log/nginx/access.log

nginx -t vous indique si la configuration peut être analysée. Le statut du service vous indique si Nginx est en cours d'exécution. Les journaux vous indiquent ce que Nginx a vu lors du traitement de la requête.

Si le problème est lié à une seule URL, reproduisez-le avec curl pour voir clairement les en-têtes et le statut :

curl -I https://example.com/problem/path
curl -v https://example.com/problem/path

Si le problème ne se produit que pour un nom d'hôte spécifique, incluez-le :

curl -I -H 'Host: app.example.com' http://127.0.0.1/

Cela sépare le routage Nginx du comportement DNS, CDN et du répartiteur de charge.

Nginx ne démarre pas ou ne se recharge pas

Un échec au démarrage est généralement dû à une erreur de syntaxe, une directive en double dans le mauvais contexte, un fichier d'inclusion manquant ou un problème de chemin de certificat.

Utilisez :

sudo nginx -t
sudo journalctl -u nginx -n 100 --no-pager

Les messages courants sont directs :

• unknown directive signifie une faute de frappe, un module non pris en charge, ou une directive placée dans la mauvaise version de Nginx.
• directive is not allowed here signifie que la directive est dans le mauvais contexte, comme placer une directive réservée à http à l'intérieur de server.
• cannot load certificate signifie que le chemin est incorrect, le fichier est manquant, ou les permissions empêchent Nginx de le lire.
• bind() to 0.0.0.0:80 failed signifie souvent qu'un autre processus utilise déjà le port.

Vérifiez les ports avec :

sudo ss -tulnp | grep ':80\|:443'

Ne rechargez pas tant que nginx -t n'a pas réussi. Un rechargement échoué conserve généralement l'ancien processus de travail en cours d'exécution, mais un redémarrage échoué peut mettre le site hors service.

(13: Permission denied) et 403 Forbidden

Permission denied apparaît dans le journal des erreurs lorsque l'utilisateur du processus de travail Nginx ne peut pas lire un fichier ou parcourir un répertoire. Un navigateur peut voir 403 Forbidden.

Trouvez d'abord l'utilisateur du processus de travail :

grep -R '^user ' /etc/nginx/nginx.conf

Sur Debian et Ubuntu, c'est souvent www-data. Sur les systèmes compatibles RHEL, c'est souvent nginx.

Pour une racine statique comme /var/www/html, Nginx a besoin de la permission d'exécution sur chaque répertoire parent et de la permission de lecture sur le fichier :

sudo find /var/www/html -type d -exec chmod 755 {} \;
sudo find /var/www/html -type f -exec chmod 644 {} \;

Évitez d'exécuter chown -R www-data:www-data par réflexe sur les répertoires d'application. Cela pourrait faire disparaître l'erreur tout en donnant au serveur web un accès en écriture dont il n'a pas besoin. Un modèle plus sûr consiste à conserver une propriété de déploiement séparée et à accorder à Nginx un accès en lecture.

Si les permissions semblent correctes, vérifiez si la requête concerne un répertoire sans fichier d'index :

location / {
    root /var/www/html;
    index index.html index.htm;
}

Si /docs/ n'a pas de index.html et que autoindex est désactivé, Nginx renvoie 403. C'est un comportement correct.

SELinux peut également provoquer des échecs de type permission sur les systèmes de la famille RHEL. Si les permissions des fichiers sont correctes mais que Nginx ne peut toujours pas lire ou servir de proxy, vérifiez les journaux d'audit avant de désactiver SELinux :

sudo ausearch -m avc -ts recent

(111: Connection refused) et 502 Bad Gateway

Connection refused signifie que Nginx a tenté de se connecter à un amont et que la cible l'a activement refusé. L'application peut être arrêtée, écouter sur une adresse différente, ou utiliser un chemin de socket qui n'existe pas.

Pour ce proxy :

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

vérifiez :

sudo ss -tulnp | grep 3000
curl -I http://127.0.0.1:3000
sudo systemctl status your-app --no-pager

Si Nginx utilise un socket Unix, vérifiez le fichier socket :

ls -l /run/gunicorn/app.sock

L'utilisateur du processus de travail doit pouvoir lire et écrire le socket.

Un 502 Bad Gateway est plus large. Nginx a atteint quelque chose en amont, mais la réponse était invalide, incomplète, fermée trop tôt, ou pas ce que Nginx attendait. Vérifiez les journaux de l'application au même horodatage que l'erreur Nginx. Cette correspondance d'horodatage est importante ; sinon, vous finissez par chercher l'exception de la veille.

Pour PHP-FPM, vérifiez que fastcgi_pass correspond au socket ou au port du pool configuré. Par exemple :

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

Ensuite, vérifiez :

sudo systemctl status php8.3-fpm --no-pager
ls -l /run/php/php8.3-fpm.sock

504 Gateway Timeout

Un 504 signifie que Nginx a attendu l'amont et n'a pas reçu de réponse en temps opportun. L'augmentation des délais d'attente peut être valide pour les rapports, les importations ou les opérations d'administration lentes, mais cela ne devrait pas être la seule solution pour un point de terminaison public qui est lent à chaque requête.

location /api/reports/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_connect_timeout 10s;
    proxy_send_timeout 60s;
    proxy_read_timeout 180s;
}

Ensuite, examinez la temporisation du backend. Ajoutez la temporisation amont aux journaux d'accès si vous ne l'avez pas déjà :

log_format proxy_timing '$remote_addr "$request" $status '
                        'request_time=$request_time '
                        'upstream_time=$upstream_response_time';

Si $upstream_response_time est élevé, l'application ou la base de données est probablement le point à examiner. Si Nginx affiche des délais d'attente mais que les journaux de l'application indiquent qu'elle a répondu rapidement, vérifiez les sauts réseau, la mise en réseau des conteneurs, la résolution DNS à l'intérieur de l'hôte, ou un répartiteur de charge entre Nginx et l'application.

413 Request Entity Too Large

413 est généralement simple : le corps de la requête est plus grand que ce que Nginx autorise. Les téléchargements, les charges utiles JSON volumineuses et les envois de formulaires peuvent le déclencher.

Définissez client_max_body_size à l'endroit le plus restreint utile :

server {
    server_name example.com;

    location /upload/ {
        client_max_body_size 100M;
        proxy_pass http://127.0.0.1:3000;
    }
}

Définir une limite globale énorme est rarement une bonne idée. La plupart des routes n'en ont pas besoin, et des corps autorisés plus grands augmentent la quantité de travail qu'un mauvais client peut imposer à votre pile.

Erreurs SSL et de certificat

Les échecs TLS semblent souvent différents selon l'endroit où vous les remarquez. Nginx peut échouer à se recharger, les navigateurs peuvent avertir à propos du certificat, ou les clients peuvent échouer une négociation.

Vérifiez les dates des certificats :

openssl x509 -in /etc/letsencrypt/live/example.com/fullchain.pem -noout -dates -subject -issuer

Vérifiez ce que le service public présente :

openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null | openssl x509 -noout -dates -subject -issuer

Si ces deux commandes montrent des certificats différents, un répartiteur de charge, un CDN ou un hôte différent peut servir le trafic.

400 Bad Request et problèmes d'en-tête

400 signifie généralement que Nginx n'a pas accepté la syntaxe de la requête. Avec les vrais navigateurs, c'est moins courant, mais les robots, les anciens clients, les proxys inhabituels ou les en-têtes surdimensionnés peuvent le provoquer.

Recherchez des messages tels que client sent too large request header. Si un cookie SSO ou d'application légitime est trop volumineux, vous devrez peut-être ajuster les paramètres du tampon d'en-tête. Traitez cela comme une correction ciblée, pas comme une première réponse. Les cookies surdimensionnés sont souvent mieux corrigés dans l'application.

Un ordre pratique des opérations

Lorsqu'un problème Nginx est en direct, utilisez un ordre reproductible :

1. Confirmez l'URL exacte, l'hôte, le code d'état et l'heure.
2. Vérifiez nginx -t et le statut du service.
3. Faites correspondre la requête dans le journal d'accès.
4. Faites correspondre le même horodatage dans le journal des erreurs.
5. Si vous utilisez un proxy, vérifiez le statut et les journaux du service amont.
6. Testez l'amont directement depuis l'hôte Nginx.
7. Apportez la plus petite modification de configuration qui correspond aux preuves.
8. Exécutez nginx -t, rechargez, et surveillez les journaux tout en retestant.

La plupart des problèmes Nginx deviennent ordinaires une fois que vous savez où l'échec s'est produit : avant Nginx, à l'intérieur de Nginx, entre Nginx et l'amont, ou à l'intérieur du service amont.