Node.js "getaddrinfo ENOTFOUND" - Fix DNS Failures Reaching the Registry

By Daniel Zoghalchali·Latchkey

Node could not resolve a hostname to an IP - getaddrinfo ENOTFOUND. The TCP connection never even started because DNS failed. Against a registry or API host this is usually a transient resolver blip or a proxy/DNS misconfiguration.

What this error means

An install, fetch, or API call fails with getaddrinfo ENOTFOUND <host>. When it is the registry host, re-running often succeeds - the classic signature of a flaky DNS lookup rather than a code problem.

Error: getaddrinfo ENOTFOUND registry.npmjs.org
    at GetAddrInfoReqWrap.onlookup [as oncomplete] (node:dns:107:26)
  errno: -3008,
  code: 'ENOTFOUND',
  hostname: 'registry.npmjs.org'

Common causes

Transient DNS resolution failure

A momentary resolver hiccup on the runner fails to resolve the host. Nothing is wrong with your project - the next attempt usually resolves fine.

Proxy, custom DNS, or a typo

A misconfigured proxy, a broken /etc/resolv.conf, an air-gapped runner, or a typo in a registry/host URL makes the name genuinely unresolvable.

How to fix it

Retry the operation on transient DNS errors

For npm specifically, raise fetch retries so a flaky lookup self-recovers.

npm config set fetch-retries 5
npm config set fetch-retry-mintimeout 10000
npm ci

Verify the host and resolver

1. Confirm the host resolves on the runner: node -e "require('dns').lookup('registry.npmjs.org', console.log)".
2. Check the registry URL in .npmrc for typos.
3. If a proxy or private DNS is required, configure it explicitly rather than relying on defaults.

How to prevent it

• Add retries so a transient DNS blip recovers automatically.
• Pin the correct registry/host URLs in committed config.
• Cache dependencies so most runs do not hit external DNS at all.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation