Error: getaddrinfo ENOTFOUND — Why the Host Name Does Not Resolve

Node.js resolves host names for http, net, fetch and most libraries with dns.lookup(), which «uses the operating system facilities to perform name resolution» and is implemented as a call to getaddrinfo(3) on libuv's threadpool (Node.js dns docs). When that call finds nothing, you get:

Error: getaddrinfo ENOTFOUND api.example.com
  { errno: -3008, code: 'ENOTFOUND', syscall: 'getaddrinfo', hostname: 'api.example.com' }

The Node.js docs define ENOTFOUND as «DNS lookup failed», a failure «of either EAI_NODATA or EAI_NONAME», and note it is not a standard POSIX error. Per getaddrinfo(3), EAI_NONAME means «The node or service is not known» and EAI_NODATA means the host exists but has no network addresses defined. In DNS terms that is NXDOMAIN or a name with no A/AAAA record.

A different code, EAI_AGAIN (getaddrinfo EAI_AGAIN), is a temporary failure: the resolver could not be reached or returned a temporary error. ENOTFOUND is a definite «no such name»; EAI_AGAIN is «could not ask».

The first row accounts for a large share of reports. http.request({ host: 'https://api.example.com' }) looks up the literal string https://api.example.com as a host name, which cannot exist. Use host: 'api.example.com' or pass the URL string as the first argument.

Name resolution inside a container uses the container's own /etc/resolv.conf, not the host's. Containers on a user-defined Docker network resolve each other by name through Docker's embedded DNS; on the default bridge network they cannot (Docker bridge docs), so a compose-style service name used with plain docker run returns ENOTFOUND. In Kubernetes, a service name resolves only through the cluster DNS and only in the right namespace: db works from the same namespace, other namespaces need db.namespace.

Corporate VPNs often provide internal names through their own resolver. When the VPN is off, or a container does not inherit the VPN's DNS settings, internal names fail with ENOTFOUND while public names keep working.

docker run --rm --network mynet busybox nslookup db
kubectl run -it --rm dnscheck --image=busybox --restart=Never -- nslookup db.default

1. Copy the host name from the error character by character. A scheme, a trailing slash, a port glued to the name or undefined points straight at the bug.
2. Resolve it the way Node.js does (through the system resolver, including /etc/hosts), then directly in DNS:

   getent hosts api.example.com      # system resolver, like dns.lookup()
   dig +short api.example.com A      # public DNS only
   dig +short api.example.com AAAA

   If getent fails but dig works, the local resolver configuration is the problem; if both fail, the record is missing.
3. Check the record in public DNS and create it if missing; see checking DNS records.
4. In containers, run the same lookup inside the container and read its /etc/resolv.conf.
5. For npm, check npm config get registry and npm config get proxy; a mistyped registry or proxy host produces the same error.

node -e "require('dns').lookup('api.example.com', (e, a) => console.log(e ? e.code : a))"
# 203.0.113.10

Run it in the same environment as the failing app (host, container or CI job). The DNS lookup shows what public DNS returns for the name.

• NXDOMAIN — the DNS answer behind most ENOTFOUND errors
• SERVFAIL — the resolver could not get an answer
• ECONNREFUSED — the name resolved, nothing listened
• TypeError: Failed to fetch — how a browser reports a failed lookup to scripts
• ERR_NAME_NOT_RESOLVED — the Chrome equivalent