Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

npm install stops with 503 Service Unavailable from the registry

Error503 Service Unavailable

Short answer

A 503 means the server answering npm's request could not serve it right now. That server is the public registry during an incident, or a proxy or private registry in between. Run npm ping and npm config get registry to see who answers, check npm's status page, and raise fetch-retries if the failures are short.

  • Applies to npm 10, Node.js 22, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find out which registry npm is really calling, then ping it. The answer tells you whether the public registry or something you run is failing.

    npm config get registry
    npm ping
  2. 2Match what you see, then jump to its fix

    1. 1npm ping fails against https://registry.npmjs.org/ from every machine and network you trynpm's own registry has an incidentFix
    2. 2npm config get registry shows a company address, or a proxy is set, and npm ping fails only on that networkA proxy or private registry in between returns the 503Fix
    3. 3The same install works on a second try a minute laterThe outage is short and npm gives up too earlyFix

What does the error look like?

  • 503 Service Unavailable

Cause 1 of 3

npm's own registry has an incident

1Check

Open npm's status page and see whether package installation is listed as degraded. It can also send incident alerts by email.

npm ping
# then open https://status.npmjs.org/

2Fix

Nothing on your side is broken. Wait for the incident to resolve and run the install again. npm already retries read requests that fail with a 5xx error, so a short incident often passes by itself.

npm install

3Verify

npm ping prints PONG with a response time.

npm ping

Confirmed by status.npmjs.org

Did this fix it?

Cause 2 of 3

A proxy or private registry in between returns the 503

1Check

npm doctor tests the connection to the configured registry and reports a non-default registry. A failure there can point at a proxy that needs configuring or blocked HTTPS access.

npm doctor connection registry
npm config get proxy
npm config get https-proxy

2Fix

Point npm at the registry you mean to use, or fix the proxy settings. If the registry is yours (a mirror or artifact server), restart or repair that service. Use your own values for the examples.

npm config set registry https://registry.npmjs.org/
npm config set https-proxy http://proxy.example.com:8080

3Verify

npm ping succeeds against the registry you configured.

npm ping

Confirmed by docs.npmjs.com

Did this fix it?

Cause 3 of 3

The outage is short and npm gives up too early

1Check

npm retries fetch-retries times (default 2), with waits between tries set by fetch-retry-mintimeout and fetch-retry-maxtimeout.

npm config get fetch-retries

2Fix

Allow more retries and a longer wait, which helps on flaky mirrors and busy CI.

npm config set fetch-retries 5
npm config set fetch-retry-mintimeout 20000

3Verify

Run the install again and watch it get through.

npm install

Confirmed by docs.npmjs.com

Did this fix it?

How do I stop it coming back?

  • Subscribe to npm's status page alerts so you know when an install failure is not your fault.
  • Set fetch-retries in the project or CI .npmrc instead of retrying whole builds by hand.
  • Keep one documented registry setting per project, so nobody installs through a stale mirror.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.