Fix it fast
Most likely: npm cannot resolve the registry hostname. This is usually a wrong registry URL, stale proxy config, VPN/DNS issue, or scoped registry mapping pointing at a host that does not exist from this machine.
1. Confirm this is your error
npm ERR! code ENOTFOUND
npm ERR! errno ENOTFOUND
npm ERR! getaddrinfo ENOTFOUND registry.npmjs.org2. Check the cause
npm config get registry
npm config get @your-scope:registry
npm ping --verbose
node -e "require('dns').lookup(new URL(process.argv[1]).hostname, console.log)" $(npm config get registry)
npm config get proxy
npm config get https-proxy3. Apply the safe fix
# Fix the registry or DNS/proxy path first, then retry.
npm ping
npm install --verbose
# If stale proxy config is set and you are not behind that proxy, clear it.
npm config delete proxy
npm config delete https-proxy4. Verify it works
npm ping
npm installDon't use unsafe shortcuts
- Do not change dependency versions before checking the registry hostname.
- Do not delete the lockfile for
ENOTFOUND, npm failed before package resolution. - Do not keep a scoped registry URL that only works on a different VPN or network.
Where the Request Failed
npm is telling you the request failed before it got a clean response back. Treat the connection path and the failing environment as the first suspects, not the package or image name.
Restore connectivity to the registry
Start by proving the failing machine can reach the right host cleanly. Until DNS, routing, proxy, and trust look sane in that exact environment, retrying the install or pull is mostly noise.
Check which registry npm is using:npm config get registry
If the package is scoped, verify scope registry mapping in .npmrc (example: @your-scope:registry=...).
Run a quick health check:npm ping
Confirm basic HTTPS connectivity from the same machine:curl -I $(npm config get registry)
If you use a proxy, verify settings:npm config get proxy and npm config get https-proxy
If you do not use a proxy, remove stale proxy config:npm config delete proxy and npm config delete https-proxy
Resolve the registry host (DNS):node -e "require(\"dns\").lookup(new URL(process.argv[1]).hostname, console.log)" $(npm config get registry)
If this works on a different network (hotspot) but fails on your office/VPN, fix DNS/VPN/proxy first.
Retry with logs:npm --verbose (keep the full output).
If this happens in CI only, compare DNS/proxy/firewall between CI and your local machine.
Manual connectivity checks
Resolve the registry host:node -e "require(\"dns\").lookup(new URL(process.argv[1]).hostname, console.log)" $(npm config get registry)
Check TLS+HTTP from the same machine:curl -v $(npm config get registry)
If behind a proxy, confirm it is used only when intended and supports HTTPS CONNECT.
Why It Happens
Usually this comes down to DNS is unstable or blocked on your network (VPN, captive portal, split-DNS, or firewall), a proxy is misconfigured (wrong proxy / https-proxy), or a corporate proxy is blocking npm traffic, or the registry endpoint is temporarily down or rate-limiting requests.
Prove the Failing Environment Can Reach It
Run npm ping and confirm it succeeds, and re-run the original command and confirm downloads complete without timeouts/resets.
How npm talks to registries
npm fetches package metadata and tarballs over HTTPS from your configured registry. Failures can happen during DNS lookup, TCP connect, TLS handshake, or while streaming the tarball. Proxy configuration (proxy / https-proxy) changes the network path and is a common root cause.
Prevent Repeat Connectivity Failures
To prevent this, use a proxy/cache registry close to your CI runners to reduce upstream variance, avoid flaky DNS by using stable resolvers in CI and on build machines, and pin Node/npm versions in CI so network behavior is consistent.
Docs and source code
github.com/npm/cli/blob/417daa72b09c5129e7390cd12743ef31bf3ddb83/lib/utils/ping.js
This is the registry request path where npm talks to the network. DNS/TLS errors like this code are raised by Node/OS during this request. - GitHub
// used by the ping and doctor commands
const npmFetch = require('npm-registry-fetch')
module.exports = async (flatOptions) => {
const res = await npmFetch('/-/ping', { ...flatOptions, cache: false })
return res.json().catch(() => ({}))
}