Deploy Error Decoder

'getaddrinfo ENOTFOUND' — fix DNS resolution failures

Quick answer: getaddrinfo ENOTFOUND <host> means the hostname couldn't be resolved to an IP — DNS found nothing. Usually it's a typo, a missing environment variable (so it resolves the literal undefined), or a service name that only exists on another network. Inside Docker, use the Compose service name; on a host, test resolution with nslookup or dig.

What the error looks like

The error names the host that failed to resolve — read it carefully:

Error: getaddrinfo ENOTFOUND api.example.com
    at GetAddrInfoReqWrap.onlookup (node:dns:107:26)
  errno: -3008, code: 'ENOTFOUND', hostname: 'api.example.com'

# a giveaway that an env var is missing:
Error: getaddrinfo ENOTFOUND undefined

ENOTFOUND is resolution, not connection: DNS returned no address, so no connection was even attempted. If the hostname is undefined or looks half-built, an env var is missing.

Why it happens

Typo in the hostname

A misspelled host simply doesn't exist in DNS.

Missing env var → 'undefined'

An unset variable makes the code try to resolve undefined or a half-built URL.

Docker service name vs localhost

A Compose service name resolves only on the Docker network — not from localhost or the host.

DNS/resolver issue or not-ready network

The resolver is misconfigured, or the app resolved before the network/DNS was up.

Diagnose it in three steps

1

Print the host the app actually used

# Log it at runtime — don't trust the config file.
console.log('connecting to', process.env.API_URL);
# 'undefined' or blank? It's a missing env var, not DNS.

2

Test resolution directly

nslookup api.example.com
dig +short api.example.com
# inside a container:
getent hosts db

3

In Docker, use the service name

# app talks to host 'db' (the compose service), not localhost
services:
  app:
    environment:
      DATABASE_URL: postgres://user:pass@db:5432/app

The real fix

Correct the name, set the var, order the start

Fix the root: correct the hostname or set the missing environment variable, and inside Docker use service names on the shared network. If it only fails at startup, the app is resolving before DNS/network is ready — add a short retry and don't connect until dependencies are reachable.

How Infraveil handles this

Ordered start, dependency health

Resolving a dependency before it's ready is a startup race Infraveil helps prevent. On your own servers, its agent health-checks services and coordinates how they start, so an app doesn't go live before the host it needs is reachable. Failures surface in one status view, and recovery is approval-gated and recorded.

Health checks confirm dependencies are reachable before traffic flows

Failures surface in one status + log view, on servers you control

Automatic restart and recovery, approval-gated and recorded

See how it works More deploy fixes

Frequently asked questions

What does 'getaddrinfo ENOTFOUND' mean?

DNS resolution failed — the hostname your app tried to look up returned no IP address. No connection was attempted because the name didn't resolve.

Why is the hostname 'undefined'?

An environment variable that should hold the host is unset, so the code resolves the literal string undefined. Set the variable and confirm it at runtime.

Why does ENOTFOUND happen in Docker?

A Compose service name resolves only on the Docker network. Connect using the service name (e.g. db), not localhost, which inside a container refers to the container itself.

How is ENOTFOUND different from ECONNREFUSED?

ENOTFOUND is a DNS/name-resolution failure — no address was found. ECONNREFUSED means the name resolved and a connection was attempted, but the target actively refused it.