how to debug npm ERR! code EAI_AGAIN in CI

TL;DR

EAI_AGAIN is a DNS resolution failure: npm could not resolve the registry hostname. In CI this is almost always transient infrastructure flakiness (the runner's DNS, a brief network blip) rather than your code. The fix stack: retry with backoff, pin a reliable DNS setup on self-hosted runners, and consider a registry mirror if it recurs. Do not change your package.json to fix it.

The query

how to debug npm ERR! code EAI_AGAIN in CI

Use this when

• npm install fails in CI with code EAI_AGAIN
• Failures are intermittent and retrying helps
• Local installs work fine
• Failures cluster around certain times or runners

Not for when

• npm authentication errors (ENEEDAUTH, 401/403)
• Corrupt cache or lockfile issues
• Registry outages (those give 500s, not DNS errors)

Steps

Step 1: Confirm it is transient, not permanent

Check whether rerunning the job succeeds. EAIAGAIN that clears on retry is infrastructure flakiness; EAIAGAIN that fails every time on one runner is that runner's DNS configuration. Expected output: classified as intermittent (most common) or persistent on specific runners.

Step 2: Add retry logic to the install step

Wrap npm install in a retry with backoff (a few attempts, growing delays). For transient DNS blips this turns red builds green with no other changes. Most CI systems have a retry mechanism or you can script a simple loop. Expected output: transient failures stop failing the build.

Step 3: Check the runner's DNS configuration

On self-hosted runners, inspect the DNS resolver setup: misconfigured or overloaded resolvers cause EAI_AGAIN under load. Point at a reliable resolver and verify resolution of the registry hostname directly from the runner. Expected output: the registry hostname resolves consistently from the runner.

Step 4: Reduce DNS dependence

Use npm's cache aggressively so installs rarely hit the network, and consider a local registry mirror or proxy for heavy CI usage. Fewer DNS lookups means fewer chances for DNS to fail. Expected output: installs succeed from cache most of the time; registry hits are the exception.

Step 5: Track frequency and escalate if it grows

Log EAI_AGAIN occurrences. Occasional blips are normal CI weather; a rising trend means the runner infrastructure or network path is degrading and needs attention from whoever runs it. Expected output: a trend line that justifies either handled by retries or an infrastructure ticket.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_LCE1akXqEqHcD60LQDyHjg