Package registry or CDN outage

What this failure means

The dependency installation step failed because the upstream package registry (npm, PyPI, Maven Central, RubyGems, etc.) is temporarily unavailable or returning errors. This is a transient infrastructure failure unrelated to the project’s code.

Symptoms

Faultline looks for one or more of these log fragments:

registry is down
npm ERR! network
registry.*unavailable
pypi.*down
npmjs.*down
maven.*unavailable
central.sonatype.*unavailable
rubygems.*unavailable

Diagnosis

Registry outages are typically short-lived (minutes to hours) and affect all projects using the registry simultaneously. The failure will resolve itself once the registry recovers.

Check registry status:

• npm: https://status.npmjs.org/
• PyPI: https://status.python.org/
• Maven Central: https://status.maven.org/
• RubyGems: https://status.rubygems.org/

Identify the outage symptom:

npm ERR! network This is a problem related to network connectivity
error: Registry returned 503 for "https://pypi.org/simple/requests/"
Could not transfer artifact from/to central: 503 Service Unavailable

Fix steps

1. Immediate: Re-run the CI job. Registry outages are often brief and the retry will succeed.

2. Configure automatic retries in your package manager:

   # npm — retry on transient errors
   npm ci --fetch-retry-mintimeout 20000 --fetch-retry-maxtimeout 120000 --fetch-retries 3
   
   # pip — retry with backoff
   pip install --retries 5 --timeout 60 -r requirements.txt
   

3. For production pipelines, configure a mirror or proxy registry that caches packages locally:

   • npm: Verdaccio or GitHub Packages as a proxy
   • PyPI: devpi or Google Artifact Registry
   • Maven: Nexus or Artifactory

4. Enable dependency caching in CI so subsequent runs do not need to reach the registry at all:

   # GitHub Actions
   - uses: actions/setup-node@v4
     with:
       cache: 'npm'
   

5. For time-critical pipelines, maintain a vendor directory with committed dependencies as a fallback.

Validation

• Check the registry status page to confirm recovery.
• Re-run the failing CI job.
• Confirm dependency installation completes without network errors.

Why it matters

Registry outages block all CI pipelines simultaneously and cannot be fixed within the project. The only mitigations are retries, caching, and mirror registries. Without these safeguards, a registry outage causes widespread pipeline failures and developer downtime.

Prevention

• Enable aggressive dependency caching so most runs do not hit the registry.
• Use a local registry proxy or artifact repository for critical projects.
• Configure retry logic in package manager invocations.
• Subscribe to registry status pages for early warning of outages.

How Faultline detects it

Use faultline explain registry-outage to see the full playbook.

faultline analyze build.log
faultline explain registry-outage

Generated from playbooks/bundled/log/network/registry-outage.yaml. Do not edit directly.