npm ENOTFOUND "request to … failed, reason: getaddrinfo ENOTFOUND" - Fix in CI

By Kaveh Alemi·Latchkey

ENOTFOUND is a DNS failure - Node could not resolve the registry hostname to an IP at all. In CI this is almost always a transient DNS blip, a wrong registry host, or a proxy that blocks name resolution.

What this error means

npm install/npm ci fails before downloading anything with getaddrinfo ENOTFOUND for the registry host. The hostname simply did not resolve, so npm never opened a connection.

npm output

npm error code ENOTFOUND
npm error syscall getaddrinfo
npm error errno ENOTFOUND
npm error network request to https://registry.npmjs.org/lodash failed,
reason: getaddrinfo ENOTFOUND registry.npmjs.org

Diagnose it: which registry, and with what credentials?

Registry errors are resolved in a precedence chain, and the effective value is rarely the one in the file you are looking at. Scoped registries, .npmrc files at several levels, and environment variables all combine before a request is made.

Terminal

# the effective, fully merged configuration
npm config list -l | grep -E "registry|_auth|always-auth"

# where each value came from
npm config get registry
npm config get @yourscope:registry

# prove the token works, independently of the install
curl -sI -H "Authorization: Bearer $NPM_TOKEN" \
  "$(npm config get registry)@yourscope%2fpackage" | head -1

Common causes

Transient DNS failure on the runner

A momentary DNS outage or a slow resolver on the CI network means the registry hostname does not resolve. A retry on a fresh runner usually succeeds.

A typo or wrong custom registry host

An .npmrc pointing at a misspelled or decommissioned registry hostname produces a permanent ENOTFOUND - the name genuinely does not exist.

A proxy or air-gapped network blocks name resolution

Behind a restrictive proxy, direct DNS to public registries can be blocked; npm must be pointed at an internal mirror whose host the runner can resolve.

How to fix it

Retry and confirm the registry host

Re-run the job, and verify the configured registry resolves from the runner.

Terminal

npm config get registry
# confirm the host resolves on the runner
node -e "require('dns').lookup('registry.npmjs.org', (e,a)=>console.log(e||a))"
npm ci

Point at a resolvable mirror

Behind a proxy, set registry to an internal mirror whose host the runner can resolve.
Raise npm fetch retries so a single DNS blip self-recovers.
Pre-warm or cache ~/.npm so most installs do not hit the network at all.

How to prevent it

Use a registry host the CI network can always resolve.
Raise fetch-retries so transient DNS blips self-heal.
Cache the npm download cache keyed on the lockfile.

Frequently asked questions

What causes npm ENOTFOUND "request to … failed, reason: getaddrinfo ENOTFOUND"?

There are 3 common causes: transient dns failure on the runner, a typo or wrong custom registry host, and a proxy or air-gapped network blocks name resolution. A momentary DNS outage or a slow resolver on the CI network means the registry hostname does not resolve.

How do I fix npm ENOTFOUND "request to … failed, reason: getaddrinfo ENOTFOUND"?

There are 2 fixes depending on which cause you have: retry and confirm the registry host and point at a resolvable mirror. Work through them in order, since the first is the most common.

What does npm ENOTFOUND "request to … failed, reason: getaddrinfo ENOTFOUND" actually mean?

npm install/npm ci fails before downloading anything with getaddrinfo ENOTFOUND for the registry host.

How do I stop npm ENOTFOUND "request to … failed, reason: getaddrinfo ENOTFOUND" happening again?

Use a registry host the CI network can always resolve. The prevention section lists 3 changes that keep it from recurring.

Can Latchkey fix this automatically?

Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.