Home › npm & Node.js

npm ERR! code ERR_SOCKET_TIMEOUT — how to fix

npm ERR! code ERR_SOCKET_TIMEOUT
npm ERR! network Socket timeout
npm ERR! network This is a problem related to network connectivity.
npm ERR! network In most cases you are behind a proxy or have bad network settings.
npm ERR! network
npm ERR! network If you are behind a proxy, please make sure that the
npm ERR! network 'proxy' config is set properly.  See: 'npm help config'

Quick fix: Retry with longer timeouts and fewer parallel sockets: npm config set fetch-timeout 600000, npm config set fetch-retries 5, npm config set maxsockets 5. Check the registry with npm config get registry and npm ping. Set or remove proxy settings (npm config delete proxy, npm config delete https-proxy). On Node 17+ IPv6 issues, try NODE_OPTIONS=--dns-result-order=ipv4first npm install.

What it means

npm connected to the registry (or a proxy/mirror), but the socket sat idle longer than allowed and npm gave up. It differs from ETIMEDOUT, where the connection itself couldn't be established (ETIMEDOUT page). Both are network problems, not problems with your package.json.

Run with more logging to see which URL timed out:

npm install --loglevel=http

Check basics:

npm config get registry      # normally https://registry.npmjs.org/
npm ping
curl -I https://registry.npmjs.org/react

Fix 1: longer timeouts, more retries, fewer sockets

A big install downloads many packages in parallel (maxsockets defaults to 15). On slow or lossy links some of those sockets starve and hit the timeout.

npm config set fetch-timeout 600000          # 10 min (default 300000)
npm config set fetch-retries 5               # default 2
npm config set fetch-retry-mintimeout 20000
npm config set fetch-retry-maxtimeout 120000
npm config set maxsockets 5
npm install

These go into ~/.npmrc. For a single run: npm install --fetch-timeout=600000 --maxsockets=5.

Fix 2: proxy settings

Behind a corporate proxy, npm needs it explicitly:

npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

If you are not behind a proxy any more (laptop at home, VPN off), stale settings cause exactly this timeout. Remove them:

npm config list            # look for proxy / https-proxy
npm config delete proxy
npm config delete https-proxy
unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy

Also check the project's .npmrc, which overrides your user config.

Fix 3: IPv6 / DNS problems

On Node 17+, DNS results are no longer sorted IPv4-first. If your network advertises IPv6 but doesn't route it, connections hang. Force IPv4 for the run:

NODE_OPTIONS=--dns-result-order=ipv4first npm install

On Windows PowerShell: $env:NODE_OPTIONS="--dns-result-order=ipv4first"; npm install. Updating to a current Node (20+) also helps, since it tries IPv4 and IPv6 in parallel.

Fix 4: a slow or broken registry mirror

If registry points at a company Artifactory/Nexus or a regional mirror, it may be slow or down. Test against the public registry:

npm install --registry=https://registry.npmjs.org/

Lockfiles store full resolved URLs. If package-lock.json was created against an unreachable mirror, npm still fetches from there; regenerate it or rewrite those URLs.

Fix 5: clean cache and retry

A half-written cache can cause repeated failures:

npm cache verify
npm cache clean --force   # if verify reports problems
rm -rf node_modules
npm install

Fix 6: CI and Docker builds

Yarn and pnpm equivalents

Last updated 2026-11-14.