The HTTP 503 Service Unavailable error indicates the npm registry is temporarily unable to handle requests. This could be due to maintenance, overload, or temporary server issues.
Fixes npm ERR! 503 Service Unavailable
# Check status
open https://status.npmjs.org
# Check npm blog/Twitter
open https://blog.npmjs.org# Check statusopen https://status.npmjs.org# Check npm blog/Twitteropen https://blog.npmjs.orgnpm ERR! 503 Service Unavailable
On this page
HTTP 503 means the server is temporarily unable to handle the request, usually due to maintenance or overload. Unlike 500 (unexpected error), 503 often indicates a planned or known temporary condition. The registry uses 503 to signal that you should retry later. This is often accompanied by a Retry-After header indicating when to try again.
Look for scheduled maintenance:
# Check status
open https://status.npmjs.org
# Check npm blog/Twitter
open https://blog.npmjs.orgIf the response includes timing info:
# Check headers
curl -I https://registry.npmjs.org
# Look for Retry-After header and wait that durationMaintenance is usually brief:
# Wait a few minutes
sleep 300
npm install
# Or use retry loop
while ! npm install; do sleep 60; doneWork with cached packages:
npm install --prefer-offline
# Or completely offline if cached
npm install --offlineUse alternative registry:
npm config set registry https://registry.npmmirror.com
# Remember to switch back after
npm config set registry https://registry.npmjs.orgFor critical systems:
1. Run local npm proxy (Verdaccio/Nexus)
2. Pre-cache all dependencies
3. Use package-lock.json with npm ci
4. Implement retry logic in automation
npm typically announces scheduled maintenance in advance. Subscribe to status.npmjs.org for notifications. For production systems, never depend directly on the public registry during deployments - use a caching proxy. Implement circuit breakers in CI/CD that handle 503 gracefully with exponential backoff.