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 :

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