How to fix npm ERR! code ECONNREFUSED npm ERR! errno ECONNREFUSED npm ERR! FetchError: request to https://registry.npmjs.org/ failed, reason: connect ECONNREFUSED in npm

npmBEGINNERMEDIUM

This error occurs when npm cannot establish a network connection to the npm registry. Common causes include proxy or firewall blocking, VPN interference, misconfigured network settings, or the registry being temporarily unreachable.

What this error means

The ECONNREFUSED error in npm indicates that the network connection to the npm registry was actively refused. This is a TCP-level error that occurs when npm attempts to connect to a server, but no process is listening on the target port, or a firewall/proxy is blocking the connection. When you run `npm install` or any command that requires fetching packages, npm tries to connect to the registry (by default https://registry.npmjs.org/). If this connection is refused, you'll see ECONNREFUSED along with the IP address and port that npm tried to reach. This error is particularly common in corporate environments with strict firewalls, when using VPNs that interfere with DNS resolution, in Docker containers with network isolation, and in WSL2 environments that have a separate virtual network stack.

How to fix "npm ERR! code ECONNREFUSED npm ERR! errno ECONNREFUSED npm ERR! FetchError: request to https://registry.npmjs.org/ failed, reason: connect ECONNREFUSED"

1Check basic network connectivity

First, verify you can reach the npm registry at all:

bash

# Test DNS resolution
nslookup registry.npmjs.org

# Test HTTPS connectivity
curl -I https://registry.npmjs.org/

If nslookup returns 127.0.0.1 or fails, you have a DNS issue. If curl fails with connection refused, the problem is network-level.

Also check if other HTTPS sites are accessible:

bash

curl -I https://google.com/

If this also fails, the issue is with your general internet connectivity, not npm specifically.

2Check and clear proxy settings

Incorrect proxy settings are a common cause. Check your current npm proxy configuration:

bash

npm config get proxy
npm config get https-proxy

If these return values but you're not behind a proxy, remove them:

bash

npm config delete proxy
npm config delete https-proxy

Also check for environment variables that might be setting a proxy:

bash

# Linux/macOS
echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $http_proxy
echo $https_proxy

# Windows PowerShell
echo $env:HTTP_PROXY
echo $env:HTTPS_PROXY

Unset any incorrect proxy environment variables for your current session:

bash

# Linux/macOS
unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxy

# Windows PowerShell
$env:HTTP_PROXY = ""
$env:HTTPS_PROXY = ""

3Configure proxy if you need one

If you're behind a corporate proxy, you need to configure npm to use it:

bash

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

If your proxy requires authentication:

bash

npm config set proxy http://username:[email protected]:8080
npm config set https-proxy http://username:[email protected]:8080

Note: Special characters in passwords must be URL-encoded. For example, @ becomes %40, # becomes %23.

Ask your IT department for the correct proxy settings if you're unsure.

4Disable VPN temporarily

VPN software often interferes with npm connections. Try temporarily disconnecting your VPN and running npm again:

bash

# Disconnect VPN, then:
npm install

If this works, your VPN is interfering. Solutions include:

1. Configure split tunneling to exclude npm registry traffic
2. Ask your IT department to whitelist registry.npmjs.org
3. Use npm while disconnected from VPN when possible

5Verify the registry URL

Check that npm is configured to use the correct registry:

bash

npm config get registry

The default should be https://registry.npmjs.org/. If it shows a different URL (especially localhost or an internal server), reset it:

bash

npm config set registry https://registry.npmjs.org/

Also check your .npmrc files for incorrect registry settings:

bash

# Check user config
cat ~/.npmrc

# Check project config (if exists)
cat .npmrc

6Clear npm cache

Corrupted cache can sometimes cause connection issues:

bash

npm cache clean --force

Then try your npm command again.

7Try using HTTP instead of HTTPS (temporary workaround)

If HTTPS is being blocked or interfered with, you can temporarily use HTTP:

bash

npm config set registry http://registry.npmjs.org/

Warning: This is insecure and should only be used as a temporary diagnostic step. Revert to HTTPS once you identify the root cause:

bash

npm config set registry https://registry.npmjs.org/

8Disable strict SSL (last resort)

If SSL/TLS inspection by corporate security tools is causing issues:

bash

npm config set strict-ssl false

Warning: This reduces security and should only be used in trusted corporate environments. A better solution is to configure npm to trust your corporate CA certificate:

bash

npm config set cafile /path/to/corporate-ca.crt

Advanced notes

### Docker Container Network Issues

If you're getting ECONNREFUSED inside Docker containers, the container might have restricted network access:

dockerfile

# Use host network mode during build (not recommended for production)
docker build --network host -t myapp .

Or configure the container to use the host's DNS:

yaml

# docker-compose.yml
services:
  app:
    dns:
      - 8.8.8.8
      - 8.8.4.4

### WSL2 Network Issues

WSL2 runs in a separate virtual network. If npm fails in WSL2 but works in Windows:

1. Check if Windows firewall is blocking WSL2 network:

powershell

# Run in PowerShell as Administrator
New-NetFirewallRule -DisplayName "WSL" -Direction Inbound -InterfaceAlias "vEthernet (WSL)" -Action Allow

2. Use Windows DNS servers in WSL2:

bash

# In WSL2, edit /etc/resolv.conf
sudo rm /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

3. Prevent WSL from auto-generating resolv.conf:

bash

# Create /etc/wsl.conf
[network]
generateResolvConf = false

### CI/CD Pipeline Issues

In CI environments, ECONNREFUSED often indicates:

1. Rate limiting: npm may temporarily block IPs that make too many requests
2. Network restrictions: CI runners may have limited outbound access
3. Caching proxy issues: Some CI systems use npm caching proxies that fail

Solutions:
- Use npm ci instead of npm install for faster, more reliable installs
- Configure a private npm registry or caching proxy (Verdaccio, Nexus, Artifactory)
- Add retry logic to your CI scripts

### Debugging Connection Issues

Get detailed information about what npm is trying to connect to:

bash

npm install --verbose 2>&1 | grep -E "(ECONNREFUSED|connect|proxy)"

Check npm's debug log for more details:

bash

cat ~/.npm/_logs/*-debug.log | tail -100

### Alternative Registries

If the main npm registry is blocked in your region, consider using a mirror:

bash

# China - Taobao mirror
npm config set registry https://registry.npmmirror.com/

# Yarn registry (also works with npm)
npm config set registry https://registry.yarnpkg.com/

Remember to switch back to the official registry when the network issue is resolved:

bash

npm config set registry https://registry.npmjs.org/

How to fix npm ERR! code ECONNREFUSED npm ERR! errno ECONNREFUSED npm ERR! FetchError: request to https://registry.npmjs.org/ failed, reason: connect ECONNREFUSED in npm

What this error means

Typical symptoms

Common causes

How to fix "npm ERR! code ECONNREFUSED npm ERR! errno ECONNREFUSED npm ERR! FetchError: request to https://registry.npmjs.org/ failed, reason: connect ECONNREFUSED"

Advanced notes

Related errors

Official resources & further reading