This error occurs when the TCP connection to the npm registry is unexpectedly terminated. Common causes include network instability, proxy misconfiguration, firewall interference, or server-side timeouts during package downloads.
The ECONNRESET error in npm indicates that the network connection was abruptly closed by the remote server or an intermediate network device. "ECONNRESET" stands for "Error: Connection Reset" and means the TCP socket was forcibly closed before the data transfer completed. When npm downloads packages, it establishes TCP connections to the registry (usually registry.npmjs.org). If any device in the network path—your firewall, corporate proxy, ISP, or the registry itself—terminates the connection unexpectedly, npm receives a "socket hang up" error. This error is particularly frustrating because it often appears intermittently. The same `npm install` command might work on retry, fail again, then succeed—depending on network conditions, server load, and timing. It's especially common in corporate networks with aggressive proxy timeouts, in CI/CD environments with concurrent builds, and on unstable network connections.
ECONNRESET is often a transient network issue. Simply retry your npm command:
npm installIf it works on retry, you experienced a temporary network hiccup. For more reliable installs, consider implementing automatic retries (covered in Advanced Notes).
Corrupted cache data can sometimes cause connection issues during verification:
npm cache clean --forceThen retry your install:
npm installThis ensures npm downloads fresh package data rather than relying on potentially corrupted cached files.
By default, npm has relatively short timeouts. For slow or unstable networks, increase them:
# Set fetch timeout to 5 minutes (300000ms)
npm config set fetch-timeout 300000
# Set fetch retry max wait to 2 minutes
npm config set fetch-retry-maxtimeout 120000
# Increase minimum timeout between retries
npm config set fetch-retry-mintimeout 20000
# Increase number of retries
npm config set fetch-retries 5These settings persist in your ~/.npmrc file. Verify with:
npm config listIf the main npm registry is experiencing issues, try a regional mirror:
# Use the Cloudflare-backed npm mirror
npm config set registry https://registry.npmmirror.com/
# Or try the Yarn registry (compatible with npm)
npm config set registry https://registry.yarnpkg.com/To revert to the default registry:
npm config set registry https://registry.npmjs.org/For China-based developers, the npmmirror (formerly cnpm/taobao) registry often provides faster, more stable connections.
If you're behind a corporate proxy, ensure npm is configured correctly:
# Set HTTP proxy
npm config set proxy http://proxy.company.com:8080
# Set HTTPS proxy
npm config set https-proxy http://proxy.company.com:8080
# If your proxy requires authentication
npm config set proxy http://username:[email protected]:8080
npm config set https-proxy http://username:[email protected]:8080If you're NOT behind a proxy but have old proxy settings:
npm config delete proxy
npm config delete https-proxyAlso check environment variables:
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $NO_PROXYWarning: Only use this temporarily for debugging. It reduces security.
Some corporate proxies perform SSL inspection that can interfere with npm:
npm config set strict-ssl falseIf this fixes the issue, work with your IT department to properly configure SSL certificates instead of leaving this disabled. To re-enable:
npm config set strict-ssl trueOlder versions of Node.js may have networking bugs or use outdated TLS versions:
# Check current versions
node --version
npm --versionUpdate to Node.js 18.16.0+ or the latest LTS version. Use a version manager for easy switching:
Using nvm (macOS/Linux):
nvm install --lts
nvm use --ltsUsing nvm-windows:
nvm install lts
nvm use ltsAfter updating Node.js, npm is automatically updated. For a manual npm update:
npm install -g npm@latestWSL2 has known networking issues that can cause ECONNRESET errors more frequently. Try these fixes:
Reset WSL networking:
# In Windows PowerShell (Admin)
wsl --shutdown
netsh winsock reset
netsh int ip resetThen restart WSL.
Use a custom DNS in WSL:
# In WSL, edit resolv.conf
sudo rm /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
sudo chattr +i /etc/resolv.confDisable generateResolvConf (prevents WSL from overwriting):
Add to /etc/wsl.conf:
[network]
generateResolvConf = falseSecurity software can interfere with npm's network connections:
Windows Defender/Firewall:
- Temporarily disable and test if npm works
- If so, add Node.js to the firewall exceptions
Corporate firewalls:
- Ensure ports 80 and 443 are open for registry.npmjs.org
- Check if your firewall blocks long-running HTTPS connections
Antivirus (Norton, Kaspersky, etc.):
- Temporarily disable web protection
- Add npm cache directory to exclusions: ~/.npm
- Add node and npm executables to exclusions
### Automatic Retry Logic for CI/CD
For CI/CD pipelines, implement retry logic to handle transient ECONNRESET errors:
GitHub Actions:
- name: Install dependencies with retry
uses: nick-fields/retry@v2
with:
timeout_minutes: 10
max_attempts: 3
retry_wait_seconds: 30
command: npm ciBash script with exponential backoff:
#!/bin/bash
max_attempts=5
attempt=1
while [ $attempt -le $max_attempts ]; do
echo "Attempt $attempt of $max_attempts"
npm install && break
attempt=$((attempt + 1))
sleep $((2 ** attempt))
done### Docker DNS Issues
Docker containers can experience DNS issues leading to ECONNRESET:
# Use Google DNS in Docker
RUN echo "nameserver 8.8.8.8" > /etc/resolv.confOr in docker-compose.yml:
services:
app:
dns:
- 8.8.8.8
- 8.8.4.4### IPv6 Issues
Some networks have problematic IPv6 configurations. Force IPv4:
npm config set prefer-offline false
npm config set prefer-online trueOr set Node.js to prefer IPv4:
export NODE_OPTIONS="--dns-result-order=ipv4first"
npm install### maxsockets Configuration
Reduce concurrent connections to avoid overwhelming proxies or firewalls:
npm config set maxsockets 3Default is 15. Lower values reduce bandwidth but improve stability on constrained networks.
### macOS Keychain Conflicts
On macOS, the Keychain can sometimes interfere with npm authentication:
# Remove npm credentials from Keychain
security delete-internet-password -s registry.npmjs.org### Debugging Network Issues
Enable verbose logging to diagnose connection problems:
npm install --loglevel verbose 2>&1 | tee npm-debug.logOr check the npm debug log:
cat ~/.npm/_logs/*-debug-*.log### Using Yarn or pnpm as Alternatives
If ECONNRESET persists with npm, alternative package managers may have better networking:
# Yarn
corepack enable
yarn install
# pnpm (often faster and more reliable)
npm install -g pnpm
pnpm installBoth have different networking implementations that may work better in your environment.
npm ERR! code ENOAUDIT npm ERR! Audit endpoint not supported
How to fix "npm ERR! code ENOAUDIT - Audit endpoint not supported"
npm ERR! code EBADDEVENGINES npm ERR! devEngines.runtime incompatible with current node version
How to fix "npm ERR! code EBADDEVENGINES - devEngines.runtime incompatible with current node version"
npm ERR! code ETOOMANYARGS npm ERR! Too many arguments
How to fix "npm ERR! code ETOOMANYARGS - Too many arguments"
npm ERR! code EINVALIDTAGNAME npm ERR! Invalid tag name: tag names cannot contain spaces
How to fix "npm ERR! code EINVALIDTAGNAME - tag names cannot contain spaces"
npm ERR! code E400 npm ERR! 400 Bad Request
How to fix "npm ERR! code E400 - 400 Bad Request" error