NPM ETIMEDOUT - Connection Error
This guide explains how to resolve the ETIMEDOUT error when installing npm packages.
Symptoms
npm error code ETIMEDOUT
npm error errno ETIMEDOUT
npm error network request to https://registry.npmjs.org/pm2 failed, reason:
npm error network This is a problem related to network connectivity.
Or when downloading tarballs:
npm http fetch GET 200 https://registry.npmjs.org/axios 21ms (cache hit)
npm http fetch GET https://registry.npmjs.org/axios/-/axios-1.13.2.tgz attempt 1 failed with ETIMEDOUT
Quick Fix (IPv6)
In most cases, the issue comes from Node.js automatic IPv4/IPv6 selection.
export NODE_OPTIONS=--no-network-family-autoselection
npm install -g pm2
To make it permanent, add to ~/.bashrc or ~/.profile:
echo 'export NODE_OPTIONS=--no-network-family-autoselection' >> ~/.bashrc
source ~/.bashrc
Other Solutions
1. Force IPv4 in npm
npm config set prefer-ipv4 true
npm install -g pm2
2. Limit Simultaneous Connections
npm opens multiple connections in parallel, which can cause timeouts:
npm config set maxsockets 1
npm install -g pm2
After resolution, you can increase to 5-10 for better performance.
3. Check npm Registry
Make sure you're using HTTPS:
npm config get registry
If result is http://..., fix it:
npm config set registry https://registry.npmjs.org/
4. Clear npm Cache
npm cache clean --force
npm install -g pm2
5. Check Network Connectivity
# Test DNS
ping -c 3 registry.npmjs.org
# Test HTTPS
curl -I https://registry.npmjs.org/pm2
6. Check DNS Configuration
cat /etc/resolv.conf
If empty or misconfigured:
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
echo "nameserver 1.1.1.1" | sudo tee -a /etc/resolv.conf
7. Check Firewall
Outgoing HTTPS traffic (port 443) must be allowed:
# UFW
sudo ufw status
# iptables
sudo iptables -L OUTPUT -n -v
8. Remove Misconfigured Proxy
npm config list
If a proxy is configured by mistake:
npm config delete proxy
npm config delete https-proxy
Diagnosis with Verbose
To understand where it's blocking:
npm install -g pm2 --verbose
You'll see HTTP requests and where the timeout occurs.
Command Summary
# Solution 1: Disable auto IPv4/IPv6 selection (recommended)
export NODE_OPTIONS=--no-network-family-autoselection
# Solution 2: Force IPv4
npm config set prefer-ipv4 true
# Solution 3: Limit connections
npm config set maxsockets 1
# Solution 4: Reset everything
npm cache clean --force
npm config set registry https://registry.npmjs.org/
# Test
npm install -g pm2
Permanent Configuration
To prevent this issue in the future, add to ~/.bashrc:
# Fix npm ETIMEDOUT
export NODE_OPTIONS=--no-network-family-autoselection
Or configure npm globally:
npm config set prefer-ipv4 true
npm config set maxsockets 5
If metadata (JSON) passes but downloads (.tgz) don't, it's usually an IPv6 or simultaneous connections issue.