getaddrinfo ENOTFOUND dans Docker et Node.js : solutions

L'erreur getaddrinfo ENOTFOUND (ou EAI_AGAIN) indique que la fonction système de résolution de noms de domaine n'a trouvé aucune adresse IP correspondant à l'hôte demandé. Cette erreur survient régulièrement dans les environnements conteneurisés (Docker) ou les applications Node.js/Go lorsqu'ils n'ont pas accès au fichier /etc/hosts de la machine hôte.

Comment corriger getaddrinfo ENOTFOUND dans Docker et Node.js

Pour corriger getaddrinfo ENOTFOUND, ajoutez la directive extra_hosts dans votre docker-compose.yml pour mapper vos domaines vers host-gateway, forcez l'ordre de résolution IPv4 dans Node.js avec dns.setDefaultResultOrder('ipv4first'), et vérifiez que votre ligne dans /etc/hosts ne comporte ni espace insécable ni protocole.

Pourquoi votre application ignore votre fichier hosts local

Lorsque vous modifiez /etc/hosts sur votre Mac ou votre PC Windows, ces entrées sont enregistrées pour votre système d'exploitation hôte uniquement.

Les 3 causes fréquentes d'erreur :

1. L'isolation réseau des conteneurs Docker : Un conteneur possède son propre espace de noms réseau et son propre /etc/hosts virtuel. Les modifications faites sur l'hôte ne sont pas transmises au conteneur.
2. La priorité IPv6 dans Node.js (Node 17 et supérieur) : Suivant la norme RFC 6724, Node.js interroge en priorité les adresses IPv6. Si votre fichier hosts ne liste que 127.0.0.1, l'appel système peut échouer.
3. Clients HTTP avec DoH (DNS over HTTPS) : Certains modules ou navigateurs contournent la libc système et contactent directement des résolveurs publics distants (qui ignorent vos domaines .test locaux).

Pour les détails sur Docker, lisez notre guide complet sur la gestion du fichier hosts avec Docker.

Tableau comparatif : ENOTFOUND vs EAI_AGAIN

1. Transmettre vos domaines hosts à Docker Compose

Pour qu'un conteneur puisse joindre vos domaines locaux déclarés sur votre machine hôte, utilisez extra_hosts :

version: '3.8'
services:
  api:
    build: .
    extra_hosts:
      - "auth.local.test:host-gateway"
      - "services.local.test:host-gateway"
    environment:
      - AUTH_URL=http://auth.local.test:8080

Sous Linux, si host-gateway n'est pas supporté par votre version de Docker Engine, vous pouvez utiliser l'adresse IP de l'interface bridge par défaut (172.17.0.1).

2. Forcer la priorité IPv4 dans Node.js

Si votre application Node.js fonctionne en dehors de Docker mais renvoie ENOTFOUND par intermittence, forcez le résolveur à tester IPv4 avant IPv6 :

Au début de votre point d'entrée (index.js ou server.js) :

import dns from 'node:dns';

// Force le traitement IPv4 en priorité
dns.setDefaultResultOrder('ipv4first');

Vous pouvez également passer l'argument lors de l'exécution en ligne de commande :

node --dns-result-order=ipv4first server.js

Consultez aussi les différences entre 127.0.0.1 et localhost.

3. Détecter les caractères invisibles ou erreurs de syntaxe

Un fichier hosts mal encodé (par exemple avec un BOM UTF-8 ou des espaces insécables insérés lors d'un copier-coller) rend la ligne illisible pour la fonction C getaddrinfo.

Validez la résolution système avec les commandes natives :

Sur macOS :

dscacheutil -q host -a name auth.local.test

Sur Linux :

getent hosts auth.local.test

Si la commande ne retourne aucune adresse IP alors que la ligne semble présente dans /etc/hosts, supprimez la ligne et réécrivez-la à la main avec une tabulation ou un espace standard :

127.0.0.1  auth.local.test
::1        auth.local.test

4. Gérer les conteneurs Alpine Linux (musl libc)

Les images Docker basées sur Alpine Linux (node:alpine, golang:alpine) utilisent la bibliothèque musl au lieu de glibc. La résolution concurrente de requêtes A et AAAA peut provoquer des timeouts EAI_AGAIN.

Pour corriger ce comportement, ajoutez cette option dans votre conteneur :

# Dans votre Dockerfile :
RUN echo "options single-request-reopen" >> /etc/resolv.conf