How to fix npm ERR! 504 Gateway Timeout in npm

npmBEGINNERMEDIUMUpdated Dec 6, 2025· 199 views

The HTTP 504 Gateway Timeout error occurs when the npm registry doesn't respond in time. This indicates network latency issues, registry overload, or proxy timeout configurations.

Quick fix

Fixes npm ERR! 504 Gateway Timeout

# Test latency
ping registry.npmjs.org

# Test download speed
curl -o /dev/null -w "%{speed_download}" https://registry.npmjs.org/lodash
  1. Test network speed to registry
  2. Increase npm timeouts
  3. Reduce concurrent connections
  4. Use npm mirror closer to you
npm — error
# Test latency
ping registry.npmjs.org
# Test download speed
curl -o /dev/null -w "%{speed_download}" https://registry.npmjs.org/lodash
npm ERR! 504 Gateway Timeout

What this error means

HTTP 504 indicates that a gateway or proxy didn't receive a timely response from the upstream server. In npm's context, this means the CDN or intermediate proxy timed out waiting for a response from the registry backend. This can be caused by slow network connections, registry overload, or aggressive timeout settings on intermediate proxies.

Typical symptoms

  • npm operations hang then fail with 504
  • Slow network connection to registry
  • Large packages fail more often
  • Error after long wait time
  • Corporate proxy timeout
  • Inconsistent failures

Common causes

  1. Slow network connection
  2. Registry under heavy load
  3. Proxy timeout too short
  4. Large package download timing out
  5. VPN adding latency
  6. Geographic distance to registry
  7. Network congestion

How to fix "npm ERR! 504 Gateway Timeout"

1Test network speed to registry

Check latency and throughput:

bash
# Test latency
ping registry.npmjs.org

# Test download speed
curl -o /dev/null -w "%{speed_download}" https://registry.npmjs.org/lodash
2Increase npm timeouts

Allow more time for slow connections:

bash
npm config set fetch-timeout 600000
npm config set fetch-retry-mintimeout 20000
npm config set fetch-retry-maxtimeout 120000
3Reduce concurrent connections

Fewer parallel downloads:

bash
npm config set maxsockets 3

This reduces load on slow connections.

4Use npm mirror closer to you

Reduce latency with regional mirror:

bash
# For China
npm config set registry https://registry.npmmirror.com

# For Europe (use company mirror if available)
5Configure proxy timeout

If behind corporate proxy:

1. Request IT increase proxy timeout
2. Typical timeout should be 5+ minutes
3. Or use local npm proxy that has better timeout handling

6Download packages individually

For persistently failing packages:

bash
# Install problematic package separately
npm install large-package --timeout 600000

# Then install rest
npm install

Advanced notes

In CI/CD on cloud providers, choose regions with good connectivity to npm CDN (US-East typically best). For air-gapped or high-latency environments, sync packages to a local registry. Consider using pnpm which has more efficient network usage. Monitor npm network requests to identify consistently slow packages.

Frequently asked questions

What does "npm ERR! 504 Gateway Timeout" mean?
HTTP 504 indicates that a gateway or proxy didn't receive a timely response from the upstream server. In npm's context, this means the CDN or intermediate proxy timed out waiting for a response from the registry backend. This can be caused by slow network connections, registry overload, or aggressive timeout settings on intermediate proxies.
How do I fix "npm ERR! 504 Gateway Timeout"?
The HTTP 504 Gateway Timeout error occurs when the npm registry doesn't respond in time. This indicates network latency issues, registry overload, or proxy timeout configurations.
What causes "npm ERR! 504 Gateway Timeout"?
Slow network connection Registry under heavy load Proxy timeout too short
Is the "npm ERR! 504 Gateway Timeout" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading