npm install stops with 503 Service Unavailable from the registry
503 Service UnavailableShort 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.
Fix it fast
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 ping2Match what you see, then jump to its fix
- 1
npm ping fails against https://registry.npmjs.org/ from every machine and network you trynpm's own registry has an incidentFix - 2
npm 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
The same install works on a second try a minute laterThe outage is short and npm gives up too earlyFix
- 1
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 install3Verify
npm ping prints PONG with a response time.
npm pingConfirmed by status.npmjs.org
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-proxy2Fix
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:80803Verify
npm ping succeeds against the registry you configured.
npm pingConfirmed by docs.npmjs.com
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-retries2Fix
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 200003Verify
Run the install again and watch it get through.
npm installConfirmed by docs.npmjs.com
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
Back end
Application Load Balancer returns 502 for a Node.js target
HTTPCode_ELB_502_Count
An ALB returns 502 when the target gives it something it cannot use: a refused or reset connection, a connection closed mid-request, a bad response, or a header over 32 K.
4 causes, each with a fixBack end
corepack enable fails: permission denied while creating the pnpm link
Internal Error: EACCES: permission denied, symlink '../lib/node_modules/corepack/dist/pnpm.js' -> '/usr/local/bin/pnpm'
corepack enable writes small link files for yarn and pnpm next to your node binary.
2 causes, each with a fixBack end
Create React App says Node is too old, and npm will not run on the new one
npm does not support Node.js v10.19.0
The shell is running an old Node.js that is below the version Create React App needs.
3 causes, each with a fixBack end
firebase deploy cannot load your functions: user code failed to load
Functions codebase could not be analyzed successfully. It may have a syntax or runtime error
The Firebase CLI loads your functions code on your machine before it deploys, to learn which functions exist.
4 causes, each with a fixBack end
firebase deploy stops because the predeploy lint step failed
Error: There was an error deploying functions
The predeploy hook in firebase.json runs npm run lint before every deploy, and a failing hook cancels the deploy.
3 causes, each with a fixBack end
fluent-ffmpeg cannot find the ffmpeg or ffprobe binary
Error: Cannot find ffprobe
fluent-ffmpeg does not bundle ffmpeg.
4 causes, each with a fix