How to fix npm ERR! 502 Bad Gateway in npm

npmBEGINNERMEDIUMUpdated Dec 6, 2025· 147 views

The HTTP 502 Bad Gateway error occurs when an intermediate server (like a CDN or proxy) receives an invalid response from the npm registry. This is typically a temporary infrastructure issue.

Quick fix

Fixes npm ERR! 502 Bad Gateway

curl -s https://status.npmjs.org/api/v2/status.json | jq

# Or visit
open https://status.npmjs.org
  1. Check npm status
  2. Retry the request
  3. Try different CDN endpoint
  4. Use npm mirror
npm — error
curl -s https://status.npmjs.org/api/v2/status.json | jq
# Or visit
open https://status.npmjs.org
npm ERR! 502 Bad Gateway

What this error means

HTTP 502 indicates that a gateway or proxy server received an invalid response from an upstream server. In npm's case, this usually means the CDN or load balancer couldn't get a proper response from the actual registry servers. This is almost always a temporary infrastructure issue and not something you can fix directly. It often affects only certain geographic regions or CDN edge locations.

Typical symptoms

  • npm install fails with 502 error
  • Specific packages fail while others work
  • Error is region-specific
  • Intermittent failures
  • Browser access to registry works
  • VPN changes affect the error

Common causes

  1. CDN edge server issues
  2. Registry backend server unreachable
  3. Load balancer problems
  4. Network routing issues
  5. Registry infrastructure maintenance
  6. DDoS mitigation affecting traffic
  7. Geographic routing problems

How to fix "npm ERR! 502 Bad Gateway"

1Check npm status

Look for known issues:

bash
curl -s https://status.npmjs.org/api/v2/status.json | jq

# Or visit
open https://status.npmjs.org
2Retry the request

502 errors are often transient:

bash
# Simple retry
npm install

# With delay
for i in 1 2 3; do npm install && break || sleep 30; done
3Try different CDN endpoint

Change DNS resolution path:

bash
# Use different DNS
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

# Or use VPN to change geographic routing
4Use npm mirror

Temporarily switch registry:

bash
npm install --registry https://registry.npmmirror.com

This bypasses the main npm CDN.

5Check network path

Identify where the issue is:

bash
# Trace the route
traceroute registry.npmjs.org

# Test direct connection
curl -v https://registry.npmjs.org/lodash
6Use cached packages

Work offline if possible:

bash
# If packages are in cache
npm install --prefer-offline

# Or use local proxy with cached packages

Advanced notes

npm uses Fastly CDN which has global edge locations. 502 errors often indicate issues at specific edge nodes. Using a VPN to appear from a different region can sometimes route around problem nodes. For production systems, maintain a warm package cache and consider using a caching proxy. Monitor npm status via their API for automated alerting.

Frequently asked questions

What does "npm ERR! 502 Bad Gateway" mean?
HTTP 502 indicates that a gateway or proxy server received an invalid response from an upstream server. In npm's case, this usually means the CDN or load balancer couldn't get a proper response from the actual registry servers. This is almost always a temporary infrastructure issue and not something you can fix directly.
How do I fix "npm ERR! 502 Bad Gateway"?
The HTTP 502 Bad Gateway error occurs when an intermediate server (like a CDN or proxy) receives an invalid response from the npm registry. This is typically a temporary infrastructure issue.
What causes "npm ERR! 502 Bad Gateway"?
CDN edge server issues Registry backend server unreachable Load balancer problems
Is the "npm ERR! 502 Bad Gateway" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading