Fix getaddrinfo ENOTFOUND in Docker and Node.js with Hosts File (2026)

The getaddrinfo ENOTFOUND error (or EAI_AGAIN) means the system resolver failed to find an IP address for the requested hostname. This error frequently occurs in Docker containers or Node.js applications when they do not share the host machine's /etc/hosts configuration.

How to fix getaddrinfo ENOTFOUND in Docker and Node.js

To fix getaddrinfo ENOTFOUND, add extra_hosts to your docker-compose.yml mapping domains to host-gateway, configure Node.js to prefer IPv4 with dns.setDefaultResultOrder('ipv4first'), and check your /etc/hosts file for non-breaking spaces or invalid formatting.

Why your application ignores the local hosts file

When you edit /etc/hosts on macOS or Windows, those rules apply only to the host operating system.

Common causes of resolution failures:

1. Docker container network isolation: A Docker container has its own network namespace and virtual /etc/hosts. Host entries are not automatically inherited.
2. Node.js IPv6 precedence (Node 17+): Per RFC 6724, Node.js queries IPv6 addresses first. If your hosts file only declares 127.0.0.1, the lookup may fail.
3. DNS over HTTPS (DoH) clients: Certain HTTP client libraries bypass standard OS resolver calls and query public DNS resolvers directly.

See also our guide to Docker hosts file management.

Comparison: ENOTFOUND vs EAI_AGAIN

1. Share host domains with Docker Compose

To make local domains resolvable inside a Docker container, configure 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

On Linux systems where host-gateway is unsupported by older Docker engines, use the default Docker bridge gateway IP (172.17.0.1).

2. Force IPv4 resolution order in Node.js

If your Node.js app runs outside Docker but fails to resolve local domains consistently, force IPv4 precedence:

Add this to the top of your main entry file (index.js or server.js):

import dns from 'node:dns';

// Prioritize IPv4 addresses in getaddrinfo lookups
dns.setDefaultResultOrder('ipv4first');

Or pass the runtime flag when launching your application:

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

Read 0.0.0.0 vs 127.0.0.1 and 127.0.0.1 vs localhost for deeper networking context.

3. Check for hidden characters and syntax issues

A hosts file saved with an invisible BOM or non-breaking spaces (often copied from web snippets) will fail to parse during C getaddrinfo syscalls.

Test resolution using native system utilities:

On macOS:

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

On Linux:

getent hosts auth.local.test

If these commands return nothing while the line is visible in /etc/hosts, remove the line and type it manually:

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

4. Fix Alpine Linux container resolution (musl libc)

Docker images based on Alpine Linux (node:alpine, golang:alpine) use musl libc instead of glibc. Parallel A and AAAA DNS lookups can lead to intermittent EAI_AGAIN timeouts.

Add this directive to your container build:

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