npm ERR! code EAI_AGAIN - DNS failure reaching the registry in CI

TL;DR

EAI_AGAIN is a DNS failure: the machine could not resolve the registry hostname. Retry once in case it is transient, then check DNS from the CI runner itself, then proxies and egress rules. The registry is rarely down when only DNS fails.

Error

npm ERR! code EAI_AGAIN  -  DNS failure reaching the registry in CI

Steps

1. Retry the install once; transient resolver hiccups are common in CI. Expected output: Either it passes (transient) or EAI_AGAIN repeats (systemic).

2. Resolve the hostname from the same runner: nslookup [registry host] or dig [registry host]. Expected output: You see whether the runner's resolver answers at all.

3. Check the runner's DNS config and any proxy variables; a proxy that cannot resolve the host fails the same way. Expected output: You find the misconfigured resolver, the dead proxy, or the egress rule blocking DNS.

4. For self-hosted registries, confirm the internal DNS record exists and the runner uses the internal resolver. Expected output: The hostname resolves and npm install proceeds.

5. As a stopgap for a blocked pipeline, point npm at a reachable mirror only if policy allows, and revert after. Expected output: CI goes green while the DNS fix lands.

When to use

• npm install fails in CI with EAI_AGAIN naming the registry host
• Local installs work but CI installs cannot resolve the same hostname
• A self-hosted registry moved or its DNS record changed

When not to use

• The hostname resolves but requests time out; that is connectivity or a down registry, not DNS
• EAI_AGAIN on every host including public ones; the runner itself has no network
• Auth failures after DNS works; that is a different error code

Variant phrasings

getaddrinfo EAI_AGAIN for the registry host in CI

The raw syscall wording of the same failure; the fix path is identical.

npm install cannot resolve a private registry hostname from the runner

Points at internal DNS or split-horizon resolution rather than the public internet.

Intermittent EAI_AGAIN on CI runners

Suggests resolver flapping or rate limits; retry with backoff and check the runner image's resolver config.

Why it happens

npm relies on the OS resolver before any HTTP happens, so a dead or misconfigured resolver fails every registry request with EAI_AGAIN. CI runners are the usual victims: minimal images, custom DNS, proxies, or egress rules that the developer laptop does not have. One bad resolver poisons the whole install.

Edge cases

• IPv6-only resolvers can fail hosts that need IPv4; test both families if resolution is inconsistent.
• Docker build containers inherit the host resolver; a laptop fix does not transfer into docker build.
• Some CI providers rotate egress IPs; a registry allowlisted by IP breaks without any DNS change.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_SkJvC-iR26eWsQWUkNXtgg