Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

npm install fails with getaddrinfo ENOTFOUND registry.npmjs.org

Errornpm error code ENOTFOUND

Short answer

ENOTFOUND means a DNS lookup for the host failed, so npm never connected. Print npm's registry and proxy settings first: a stale mirror, a dead proxy variable or a bad .npmrc line is the usual cause. If those are clean, test DNS from the same shell, especially inside a container.

  • Applies to npm 10, npm 11, Node.js 22, Docker Engine 27
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    See which registry and proxies npm will actually use.

    npm config get registry
    npm config get proxy
    npm config get https-proxy
  2. 2Match what you see, then jump to its fix

    1. 1npm config get proxy or https-proxy prints a value you did not expectA proxy setting or proxy environment variable points at a host that does not resolveFix
    2. 2npm config get registry does not print https://registry.npmjs.org/The registry setting is a wrong or retired hostFix
    3. 3npm works on the host but fails only in a container build or runThe container or its network has no working DNSFix

What does the error look like?

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

Cause 1 of 3

A proxy setting or proxy environment variable points at a host that does not resolve

1Check

npm honours HTTP_PROXY, HTTPS_PROXY and their lowercase forms, as well as its own proxy and https-proxy settings. An old value left from another network makes every request fail.

env | grep -i proxy
npm config get proxy

2Fix

Remove the stale setting, or set the right one. Use noproxy for hosts that must bypass the proxy.

npm config delete proxy
npm config delete https-proxy
unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy

3Verify

Run the install again.

npm install

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 3

The registry setting is a wrong or retired host

1Check

The default registry is https://registry.npmjs.org/. A line in .npmrc may override it with a host that no longer exists.

npm config get registry
grep -n registry .npmrc ~/.npmrc 2>/dev/null

2Fix

Delete the override or set the default back.

npm config set registry=https://registry.npmjs.org/

3Verify

Run the install again.

npm install

Confirmed by docs.npmjs.com

Did this fix it?

Cause 3 of 3

The container or its network has no working DNS

1Check

Containers on the default bridge copy the host's DNS servers; user-defined networks use Docker's embedded DNS at 127.0.0.11. Node.js reports ENOTFOUND when the DNS lookup fails. Look up the name from inside the container.

docker run --rm node:22 getent hosts registry.npmjs.org
docker run --rm node:22 cat /etc/resolv.conf

2Fix

Fix DNS on the Docker host first. If you must, name the DNS servers for that container with --dns.

docker run --rm --dns 1.1.1.1 node:22 getent hosts registry.npmjs.org

3Verify

The name resolves inside the container.

docker run --rm --dns 1.1.1.1 node:22 getent hosts registry.npmjs.org

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Keep proxy settings in one place per machine and remove them when you leave the network that needed them.
  • Commit a project .npmrc only for settings the whole team needs, and document any custom registry.
  • Print npm config get registry as the first step in a CI job that has network problems.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.