Error: getaddrinfo ENOTFOUND hostname means DNS resolution itself failed — Node.js couldn't translate the hostname you're trying to connect to into an actual IP address, which happens before any TCP connection is even attempted, making this a distinctly earlier-stage failure than ECONNREFUSED or ETIMEDOUT.
This error means the DNS lookup for the specified hostname returned no result — commonly a genuine typo in the hostname, an environment variable pointing at the wrong value, a service name that only resolves inside a specific network context (like a Docker network or internal DNS) being used outside that context, or an actual DNS outage.
Why This Error Happens
getaddrinfo is the underlying system call Node.js uses to resolve a hostname to an IP address, part of establishing any network connection to a named host. ENOTFOUND means that resolution came back empty — the hostname genuinely doesn't exist as far as the DNS resolver being used could determine, distinct from a connection being refused or timing out (both of which require successful hostname resolution first).
Reproducing and Diagnosing the Error
A typo'd or misconfigured hostname:
const response = await fetch("https://ap.example.com/data"); // typo: "ap" instead of "api"
// Error: getaddrinfo ENOTFOUND ap.example.com
A Docker service name used outside its container network context:
const client = new pg.Client({ host: "postgres-db" }); // Docker Compose service name
await client.connect();
// Error: getaddrinfo ENOTFOUND postgres-db
// (works inside the Docker network, fails when run directly on the host machine)
Diagnosing with a direct DNS lookup, independent of your application:
nslookup api.example.com
# or: dig api.example.com
# NXDOMAIN or no answer confirms the hostname genuinely doesn't resolve
Core Concepts Behind This Error
A genuine typo in the hostname, or an incorrect value in an environment variable, is the single most common cause — checking the exact hostname being resolved (logging it explicitly if it's constructed dynamically) against what you actually intended is often the fastest path to the fix.
Docker and container networking use their own internal DNS resolution scoped to the container network, meaning a service name that resolves correctly from inside a container (or from another container on the same Docker network) will fail with ENOTFOUND if the same hostname is used from the host machine directly, or from a container not on that same network.
Environment-specific configuration (a hostname correct for staging but not production, or vice versa) commonly causes this error to appear only in one environment, pointing toward a configuration management issue rather than a code bug — worth checking environment variables specifically when the error is environment-specific.
A genuine DNS provider outage or misconfigured DNS records for a domain you control is a less common but real cause, worth checking directly (via dig/nslookup against a known-working external DNS resolver) when the hostname should unquestionably be correct and was working previously.
Fixing "getaddrinfo ENOTFOUND"
Fix 1: Verify the exact hostname being resolved matches what you actually intend, logging it explicitly if constructed from configuration or environment variables:
const dbHost = process.env.DB_HOST;
console.log("Connecting to:", dbHost); // verify this is actually correct
const client = new pg.Client({ host: dbHost });
Fix 2: For Docker/container networking issues, ensure the hostname is only used within the correct network context, using localhost or the actual host machine's address when connecting from outside the container network:
# docker-compose.yml — service name "postgres-db" resolves correctly
# only for other services defined in this same compose file
services:
app:
environment:
DB_HOST: postgres-db # correct: used by another service in the same network
postgres-db:
image: postgres
// From the host machine directly (outside Docker), use localhost with the mapped port instead
const client = new pg.Client({ host: "localhost", port: 5432 });
Fix 3: Verify environment-specific configuration is actually correct for the environment currently running, particularly after a deployment or environment promotion:
echo $DB_HOST # confirm this matches the expected value for this specific environment
Fix 4: For a genuine DNS resolution issue with a domain you control, verify DNS records directly and check your DNS provider's status:
dig api.example.com @8.8.8.8 # query directly against a known-reliable external resolver
Why Does This Error Sometimes Happen Only in Docker, Not Locally?
Because Docker containers have their own internal DNS resolution scoped to the specific Docker network they're part of, resolving service names that simply don't exist outside that network context — a hostname that works perfectly when your application runs inside a Docker Compose network will fail with ENOTFOUND if the same code (with the same hostname) runs directly on the host machine or in a different, unconnected network, since that internal DNS entry genuinely doesn't exist in that context.
Preventing This Error in Production
Keep hostname configuration explicit and environment-specific, verified as part of your deployment process rather than assumed to be correct, and log the actual resolved hostname value when debugging connection issues rather than guessing. For containerized applications, be deliberate about which hostnames are meant for internal container-network resolution versus external, host-visible addresses, since mixing the two contexts is a common and easily overlooked source of this error.
If you hit this error, verify the exact hostname value being resolved first (log it explicitly), then check whether it's a genuine typo, an environment-specific misconfiguration, or a Docker networking context mismatch — the fix differs for each.