## 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
```text
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. EAI_AGAIN that clears on retry is infrastructure flakiness; EAI_AGAIN 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