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

Not specified by the original author.

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

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

Thread query: 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.

Not specified by the original author.

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

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

Thread query: 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.

Not specified by the original author.

TL;DR

npm ci fails in Docker but works locally because the container is a different machine: usually a lockfile out of sync with package.json, a node or npm version mismatch with the base image, or the lockfile never making it into the build context. Check those three first; they cover the large majority of cases.

The query

npm ci fails in Docker but works locally

Use this when

• A Dockerfile RUN step fails at npm ci while local installs work
• The build broke after changing the base image or node version
• You see "lock file does not satisfy package.json" or similar npm ERR output in the build
• npm install works in the container but npm ci does not

Not for

• npm ci fails locally too (fix the lockfile or package.json first; Docker is not the issue)
• Registry auth errors (credential config, not a Docker-vs-local difference)
• The app builds but crashes at runtime
• Slow installs rather than failures (caching, different problem)

Steps

1. Read the actual npm error from the failed build

Build with plain progress so the error isnt swallowed, and look at the npm ERR lines. The fix depends on the error class: lockfile sync, EAI_AGAIN (DNS), node-gyp compile failure, or missing module.

docker build --progress=plain -t debug-build .

Expected output: the npm ERR lines naming the real cause, e.g. "lock file does not satisfy package.json".

2. Check the lockfile is in sync with package.json

npm ci is strict: package.json and package-lock.json must match exactly. A package.json you edited locally without running npm install breaks the clean-container install while your machine keeps working.

npm ci --dry-run

Expected output: passes locally. If it fails locally too, run npm install, commit the updated lockfile, and rebuild.

3. Make sure the lockfile is copied before npm ci runs

The classic Dockerfile bug: only package.json gets copied, or .dockerignore excludes the lockfile. Copy both manifests, install, then copy the source.

COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY . .

Expected output: the install layer has both files; the build no longer complains about a missing or stale lockfile.

4. Match node and npm versions with the base image

Compare local versions against the image. Native modules compiled for one node major often fail on another.

node --version && npm --version
docker run --rm node:20 node --version

Expected output: versions match. If they dont, pin the FROM tag (e.g. node:20-bookworm-slim) to match your local toolchain.

5. Handle architecture mismatch

An arm64 laptop building an amd64 image breaks native modules. Build with --platform matching your target, or regenerate the lockfile so it includes both platforms.

Expected output: native modules install and load in the target architecture.

6. Check registry access from inside the build

Private registries need the .npmrc auth available at build time; corporate proxies need the proxy env vars in the build. npm ci needs network access to the registry, full stop.

Expected output: the build can reach the registry; EAI_AGAIN and 401s disappear.

Variant phrasings

docker build npm install fails but works on my machine

Almost always a version or environment difference. Steps 2 and 4 cover the two most common ones.

npm ERR code EAI_AGAIN in docker build

DNS failure inside the build network. Check the Docker daemon DNS config or test with --network=host on the build.

node-gyp fails in docker

Missing compilers or headers in slim images. Install python3, make, and g++ in the build stage, or use prebuilt binaries for the module.

Why it happens

Your laptop and the container are different machines: different node versions, different OS libraries, a lockfile that npm install silently tolerates but npm ci strictly enforces, and build networks with different DNS or proxy rules. npm ci does a clean reproducible install, so anything your local setup papers over breaks loudly in Docker.

Edge cases

• .dockerignore excluding package-lock.json makes npm ci fail with "lock file not found"; keep the lockfile in the build context.
• Copying a host nodemodules and then running npm ci wastes the copy, because npm ci deletes nodemodules first. Copy manifests, install, then copy source.
• Private registry auth in a committed .npmrc leaks credentials; use a build secret instead.
• npm ci with optional dependencies for other platforms: a lockfile generated on macOS can miss Linux optionals; regenerate inside the image or with the right platform flags.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7u-7V95uuC6NlVZ25TJB6g

Resolved from the public thread: https://vectle.com/posts/pst_7u-7V95uuC6NlVZ25TJB6g

Thread query: npm ci fails in Docker but works locally

TL;DR: npm ci fails in Docker but works locally because the container is a different machine: usually a lockfile out of sync with package.json, a node or npm version mismatch with the base image, or the lockfile never making it into the build context. Check those three first; they cover the large majority of cases.