Erreurs courantes de Nginx et correctifs : guide pratique de dépannage

Introduction

Nginx équipe une grande partie du web, mais lorsqu'il échoue, les messages d'erreur peuvent être laconiques et la cause racine cachée derrière des couches de configuration et de comportement réseau. Ce guide rassemble les erreurs Nginx les plus courantes, explique ce que chacune signifie réellement et vous fournit des correctifs pratiques, étape par étape. Il s'adresse aux développeurs, consultants DevOps et équipes techniques de startups qui doivent résoudre rapidement et en toute sécurité les problèmes de production.

Nous mettrons l'accent sur la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés plutôt que des secrets, vérifier le résultat et documenter comment récupérer si l'état attendu n'est pas atteint. Chaque correctif inclut les commandes, les sorties attendues et les étapes de récupération nécessaires.

Inventaire de version et d'environnement

Avant de toucher à quoi que ce soit, sachez exactement ce que vous exécutez. Commencez par identifier la version de Nginx installée, la topologie de déploiement (serveur nu, Docker, ingress Kubernetes) et le composant concerné. Cela vous évite d'appliquer un correctif incompatible avec votre configuration.

Exécutez la commande en lecture seule suivante pour obtenir la version et les options de compilation :

nginx -v

Sortie attendue (exemple) :

nginx version: nginx/1.24.0

Si vous avez besoin de plus de détails :

nginx -V

Cela affiche la version, les arguments de configuration et les chemins des modules. Par exemple :

nginx version: nginx/1.24.0
built by gcc 12.2.0 (Debian 12.2.0-14)
built with OpenSSL 3.0.9 30 May 2023
TLS SNI support enabled
configure arguments: --prefix=/etc/nginx --sbin-path=/usr/sbin/nginx --modules-path=/usr/lib/nginx/modules --conf-path=/etc/nginx/nginx.conf ...

Vérifiez également les processus en cours et les droits de propriété :

ps aux | grep nginx

La sortie attendue montre généralement un processus maître exécuté en tant que root et des processus travailleurs avec l'utilisateur configuré (souvent www-data ou nginx).

Si vous utilisez Docker, inspectez le conteneur :

docker ps --filter name=nginx

Et pour l'ingress Kubernetes :

kubectl get pods -n ingress-nginx -o wide

Prérequis : vous avez besoin d'un accès shell au serveur ou au conteneur et de la permission d'exécuter ces commandes en lecture seule. Le rayon d'impact de ces observations est nul ; elles ne modifient rien. Vérifiez que vous pouvez exécuter nginx -t plus tard pour tester les changements de configuration.

Chemin de configuration sûr

L'une des sources les plus fréquentes d'erreurs Nginx est une mauvaise configuration. Suivez toujours un chemin sûr : validez avant de recharger et conservez une sauvegarde.

Étape 1 : Localiser et sauvegarder la configuration

Trouvez votre fichier de configuration principal :

nginx -t 2>&1 | grep -i 'configuration file'

La sortie attendue indique le chemin, par exemple :

the configuration file /etc/nginx/nginx.conf syntax is ok

Faites une sauvegarde horodatée avant de modifier :

sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.backup.$(date +%Y%m%d%H%M%S)

Étape 2 : Effectuer une modification minimale

Ne changez qu'un élément ciblé à la fois. Par exemple, si vous devez ajouter un nouveau bloc serveur, créez un fichier séparé dans /etc/nginx/conf.d/ au lieu de modifier directement le fichier principal.

Exemple de nouveau bloc serveur pour un simple proxy inverse :

server {
    listen 80;
    server_name example.com;

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

Placez ce contenu dans /etc/nginx/conf.d/example.com.conf.

Étape 3 : Tester la configuration

Effectuez toujours une vérification syntaxique avant de recharger :

sudo nginx -t

Sortie attendue en cas de succès :

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

En cas d'erreur, elle indique le fichier et le numéro de ligne, par exemple :

nginx: [emerg] unknown directive "proxy_passs" in /etc/nginx/conf.d/example.com.conf:5
nginx: configuration file /etc/nginx/nginx.conf test failed

Étape 4 : Recharger ou redémarrer

Préférez un rechargement progressif pour éviter de couper les connexions :

sudo systemctl reload nginx

Ou, si vous utilisez Docker :

docker exec <nom_du_conteneur> nginx -s reload

Vérifiez que le rechargement a réussi et que le service est actif :

sudo systemctl status nginx

Recherchez Active: active (running) et aucune erreur dans les journaux récents.

Chemin de récupération : si la nouvelle configuration pose problème, restaurez la sauvegarde :

sudo cp /etc/nginx/nginx.conf.backup.<horodatage> /etc/nginx/nginx.conf
sudo nginx -t && sudo systemctl reload nginx

Vérification et diagnostic

Lorsque Nginx se comporte mal, vos premiers outils de diagnostic sont les journaux d'erreurs et d'accès. Par défaut, ils se trouvent dans /var/log/nginx/error.log et /var/log/nginx/access.log, mais les chemins peuvent varier. Vérifiez votre configuration :

grep -R 'error_log\|access_log' /etc/nginx/

Les formats de journaux courants incluent les horodatages, les adresses IP des clients, les lignes de requête et les réponses en amont. Suivez le journal d'erreurs pendant la reproduction du problème :

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

Recherchez les lignes avec des niveaux de gravité comme [error], [crit] ou [emerg]. Par exemple, une erreur typique connect() failed se présente ainsi :

2023/10/02 14:33:21 [error] 1234#1234: *1 connect() failed (111: Connection refused) while connecting to upstream, client: 203.0.113.5, server: example.com, request: "GET / HTTP/1.1", upstream: "http://127.0.0.1:3000/", host: "example.com"

Cela indique que le service en amont sur 127.0.0.1:3000 n'accepte pas les connexions. Une autre erreur courante est upstream timed out :

[error] 1234#1234: *2 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 203.0.113.5, server: example.com, request: "GET /api/data HTTP/1.1", upstream: "http://127.0.0.1:5000/api/data", host: "example.com"

Utilisez curl pour tester depuis le serveur lui-même et vérifier les codes de statut HTTP :

curl -I http://localhost

Sortie attendue pour un serveur sain :

HTTP/1.1 200 OK
Server: nginx/1.24.0
...

Si vous obtenez une erreur 502 Bad Gateway, le service en amont est en panne ou mal configuré. Voir la section Modes de défaillance ci-dessous.

Modes de défaillance et récupération

Voici les erreurs Nginx les plus courantes, leurs causes et les correctifs pratiques.

502 Bad Gateway

Signification : Nginx ne peut pas obtenir de réponse valide du serveur en amont.

Causes :

• Le service en amont ne fonctionne pas ou a planté.
• Mauvaise adresse ou port en amont dans proxy_pass.
• Pare-feu bloquant la connexion.
• Le service en amont est surchargé et expire.

Diagnostic :

Vérifiez si le service en amont écoute sur le port attendu. Par exemple, si votre proxy_pass est http://127.0.0.1:3000, exécutez :

ss -tlnp | grep 3000

Ou utilisez curl directement :

curl -v http://127.0.0.1:3000/

Si le service en amont est une application Node.js, vérifiez son processus :

ps aux | grep node

Correctif :

• Démarrez ou redémarrez le service en amont.
• Corrigez l'adresse en amont dans la configuration Nginx, puis exécutez nginx -t et rechargez.
• Si le service en amont est lent, augmentez les délais d'attente dans le bloc location :

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_connect_timeout 60s;
    proxy_read_timeout 60s;
    proxy_send_timeout 60s;
}

Vérification de récupération : Après correction, rechargez Nginx et testez avec curl -I pour confirmer une réponse 200.

404 Not Found

Signification : Nginx ne trouve pas la ressource demandée.

Causes :

• Directive root ou alias incorrecte.
• Fichier manquant ou chemin incorrect.
• Le bloc location ne correspond pas à la requête.

Diagnostic :

Consultez le journal d'accès pour la requête et le bloc location utilisé. Par exemple :

203.0.113.5 - - [02/Oct/2023:14:45:10 +0000] "GET /images/logo.png HTTP/1.1" 404 153 "-" "Mozilla/5.0"

Examinez votre bloc serveur pour voir quel location correspond à /images/. Une erreur courante consiste à utiliser root lorsqu'il faut alias ou vice versa.

Correctif :

• Corrigez le chemin root ou alias. Exemple pour alias :

location /images/ {
    alias /var/www/assets/images/;
}

• Assurez-vous que le fichier existe et a les bonnes permissions :

ls -l /var/www/assets/images/logo.png

Vérification de récupération : Rechargez Nginx et demandez à nouveau l'URL ; attendez-vous à un 200.

403 Forbidden

Signification : Nginx comprend la requête mais refuse de l'exécuter, généralement en raison de permissions.

Causes :

• Permissions de fichier trop restrictives.
• Fichier d'index manquant et liste de répertoire désactivée.
• Politique SELinux ou AppArmor bloquant l'accès.

Diagnostic :

Recherchez dans le journal d'erreurs des lignes telles que :

[error] 1234#1234: *3 directory index of "/var/www/html/" is forbidden

Ou des erreurs de permission refusée :

[error] 1234#1234: *4 open() "/var/www/html/index.html" failed (13: Permission denied)

Correctif :

• Assurez-vous que l'utilisateur travailleur Nginx (par exemple, www-data) dispose des permissions de lecture et d'exécution sur le répertoire et de lecture sur les fichiers :

sudo chown -R www-data:www-data /var/www/html
sudo chmod -R 755 /var/www/html

• Si la liste de répertoire est prévue, ajoutez autoindex on; dans le bloc location.
• Pour SELinux, mettez temporairement en mode permissif pour tester :

sudo setenforce 0

Si cela résout le problème, ajustez la politique ou définissez le bon contexte :

sudo chcon -R -t httpd_sys_content_t /var/www/html

Puis réactivez le mode strict :

sudo setenforce 1

Vérification de récupération : Rechargez et demandez l'URL ; attendez-vous à un 200 ou à une liste de répertoire.

504 Gateway Timeout

Signification : Nginx n'a pas reçu de réponse en temps voulu du service en amont.

Causes :

• Le traitement en amont est trop long (par exemple, requête de base de données lente, calcul lourd).
• proxy_read_timeout trop bas.
• Le service en amont est bloqué ou suspendu.

Diagnostic :

Consultez le journal d'erreurs :

[error] 1234#1234: *5 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 203.0.113.5, server: example.com, request: "GET /slow-endpoint HTTP/1.1", upstream: "http://127.0.0.1:5000/slow-endpoint", host: "example.com"

Correctif :

• Augmentez les délais d'attente dans la configuration du proxy :

location / {
    proxy_pass http://127.0.0.1:5000;
    proxy_connect_timeout 60s;
    proxy_read_timeout 300s;
    proxy_send_timeout 300s;
}

• Optimisez l'application en amont pour répondre plus rapidement (par exemple, ajoutez de la mise en cache, optimisez les requêtes).
• Si le service en amont est un microservice, envisagez de rendre la requête asynchrone ou d'utiliser une file d'attente.

Vérification de récupération : Rechargez Nginx et testez à nouveau l'endpoint lent, en vous assurant qu'il répond dans le nouveau délai.

413 Request Entity Too Large

Signification : Le client a envoyé un corps de requête plus volumineux que ce que Nginx autorise.

Causes :

• La directive client_max_body_size est réglée trop bas (par défaut 1 Mo).

Diagnostic :

Le journal d'erreurs peut ne pas montrer grand-chose ; le client reçoit le statut 413. Vérifiez votre configuration pour client_max_body_size :

grep -R client_max_body_size /etc/nginx/

Correctif :

• Augmentez la limite dans le contexte approprié (http, server ou location). Par exemple, pour autoriser des téléversements de 20 Mo globalement :

http {
    client_max_body_size 20m;
    ...
}

Ou pour un emplacement spécifique :

location /upload {
    client_max_body_size 100m;
    ...
}

• Vérifiez également client_body_timeout et client_body_buffer_size si nécessaire.

Vérification de récupération : Rechargez Nginx et tentez à nouveau le téléversement ; il devrait réussir.

Nginx ne démarre pas : "bind() to 0.0.0.0:80 failed (98: Address already in use)"

Signification : Un autre processus écoute déjà sur le port 80 (ou 443).

Causes :

• Un autre serveur web (par exemple, Apache) est en cours d'exécution.
• Une autre instance Nginx est déjà en cours d'exécution.
• Une mauvaise configuration amène Nginx à essayer de se lier au même port plusieurs fois.

Diagnostic :

L'erreur apparaît lors de l'exécution de nginx -t ou au démarrage de Nginx. Vérifiez ce qui écoute sur le port 80 :

sudo ss -tlnp | grep ':80'

La sortie attendue peut montrer Apache ou un autre processus Nginx. Vérifiez également la présence de plusieurs directives listen dans votre configuration.

Correctif :

• Arrêtez le service en conflit, par exemple sudo systemctl stop apache2 (si Apache).
• Si une autre instance Nginx est en cours d'exécution, arrêtez-la d'abord ou utilisez un autre port.
• Assurez-vous de ne pas avoir de directives listen en double dans le même bloc serveur.

Vérification de récupération : Après résolution du conflit, démarrez Nginx avec sudo systemctl start nginx et vérifiez l'état.

Pièges courants et comment les éviter

Même les opérateurs expérimentés commettent des erreurs. Voici des pièges fréquents avec Nginx et comment récupérer.

1. Ne pas tester la configuration avant de recharger

Pourquoi cela arrive : Supposer que le changement est trivial ou être sous pression temporelle.

Éviter : Exécutez toujours nginx -t après avoir modifié un fichier de configuration. Si le test échoue, Nginx ne rechargera pas et votre serveur en cours d'exécution reste inchangé.

Récupération : Si vous avez rechargé et cassé quelque chose, restaurez la configuration de sauvegarde et rechargez à nouveau.

2. Modifier les fichiers de configuration sans contrôle de version

Pourquoi cela arrive : Des corrections rapides directement sur le serveur sans dépôt.

Éviter : Conservez toutes les configurations Nginx dans un dépôt Git. Déployez les changements via un pipeline qui exécute nginx -t avant l'application.

Récupération : Utilisez git diff pour voir les changements et revenir à un commit connu et fonctionnel.

3. Utiliser des directives if dans les blocs location pour une logique complexe

Pourquoi cela arrive : Le if de Nginx est notoirement délicat et peut conduire à un comportement inattendu car il fait partie du module de réécriture et n'est pas un conditionnel généraliste.

Éviter : Préférez utiliser map, try_files ou des blocs location séparés pour la logique de routage. Si vous devez utiliser if, limitez-le aux instructions return ou rewrite.

Récupération : Simplifiez la configuration et testez minutieusement dans un environnement de préproduction.

4. Ignorer la croissance des fichiers journaux

Pourquoi cela arrive : Ne pas configurer la rotation des journaux ou ne pas surveiller l'espace disque.

Éviter : Configurez logrotate pour les journaux Nginx et surveillez l'utilisation du disque.

Récupération : Si les journaux remplissent le disque, tronquez-les et configurez immédiatement la rotation :

sudo truncate -s 0 /var/log/nginx/error.log
sudo truncate -s 0 /var/log/nginx/access.log

Puis configurez logrotate.

5. Ne pas définir de délais appropriés pour les requêtes longues

Pourquoi cela arrive : Les délais par défaut sont souvent trop courts pour les endpoints lourds.

Éviter : Analysez les temps de réponse attendus de votre application et définissez des valeurs appropriées pour proxy_read_timeout, proxy_connect_timeout et proxy_send_timeout.

Récupération : Augmentez les délais et rechargez ; surveillez le journal d'erreurs pour d'autres expirations.

6. Coder en dur les adresses IP et les ports

Pourquoi cela arrive : Configuration rapide pour un serveur spécifique.

Éviter : Utilisez des variables d'environnement ou la découverte de services pour les adresses en amont dans les environnements dynamiques. Pour les configurations statiques, utilisez des variables et des fichiers inclus pour centraliser.

Récupération : Refactorisez pour utiliser des variables ; si un service en amont change, vous ne mettez à jour qu'un seul endroit.

Liste de contrôle des opérations

Utilisez cette liste de contrôle pour toute session de dépannage Nginx. Attribuez chaque élément à un responsable unique et définissez une cadence de révision.

Cette liste garantit que chaque changement est observé, délimité et vérifié par un responsable désigné, réduisant ainsi le risque d'actions non coordonnées.

Conclusion

Nginx est fiable, mais les mauvaises configurations et les problèmes en amont sont courants. Ce guide a passé en revue les erreurs les plus fréquentes, les correctifs pratiques et les pratiques opérationnelles sûres. Commencez toujours par l'observation : connaissez votre version, consultez les journaux et confirmez l'erreur réelle avant de modifier quoi que ce soit. Utilisez le chemin de configuration sûr : sauvegarde, modification, test, rechargement et vérification. Soyez conscient des pièges courants comme les configurations non testées et les journaux ignorés. Enfin, adoptez la liste de contrôle des opérations pour attribuer les responsabilités et assurer une gestion cohérente des incidents.

Comme prochaine étape, choisissez une vérification à faible risque dans cet article, enregistrez l'état actuel, exécutez le contrôle documenté et comparez le résultat avec le signal attendu. Ensuite, passez en revue vos dépendances telles que l'ingress Kubernetes, Docker ou les permissions Linux sous-jacentes. Un flux de travail opérationnel fiable rend les défaillances visibles, protège les valeurs sensibles et définit la récupération avant qu'un incident ne force la décision.