What does npm:ERR_SOCKET_TIMEOUT mean?

npm hit a socket timeout while waiting for registry network I/O, usually because of slow connections, proxies, or an overloaded registry.

npm ERR! code ERR_SOCKET_TIMEOUT

Q: How do I prevent npm:ERR_SOCKET_TIMEOUT in CI?

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. Pin Node/npm versions in CI so network behavior is consistent.

Q: How can I manually validate npm:ERR_SOCKET_TIMEOUT?

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.

Fix it fast

Most likely: npm connected to the registry path, but the socket sat idle too long while fetching metadata or a tarball, usually because of a slow registry, proxy, VPN, or CI network path.

1. Confirm this is your error

npm ERR! code ERR_SOCKET_TIMEOUT

2. Check the cause

npm config get registry
npm ping --verbose
curl -I $(npm config get registry)
npm config get proxy
npm config get https-proxy
npm config get fetch-timeout

3. Apply the safe fix

# Confirm the registry path is reachable, then give slow fetches more time.
npm ping
npm config set fetch-timeout 600000
npm config set fetch-retry-maxtimeout 120000
npm install --verbose

4. Verify it works

npm ping
npm install

Don't use unsafe shortcuts

Do not change package versions first, this is a transport timeout.
Do not disable TLS checks to work around a slow or flaky connection.
Do not assume a local retry fixed CI if CI still uses a different proxy, VPN, or registry route.

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

If you are on a slow network, temporarily increase fetch timeouts:npm config set fetch-timeout 600000

You can also increase retry windows:npm config set fetch-retry-maxtimeout 120000 (then retry).

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 the network path to the registry is unstable (proxy, VPN, firewall, or transient outages), a proxy is misconfigured (wrong proxy / https-proxy), or a corporate proxy is blocking npm traffic, or the registry is slow to respond (or the connection is being throttled), so requests time out mid-install.

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(() => ({}))
}