the agent assumed CI and local used the same Node version — the

Not specified by the original author.

TL;DR The CI runner is on a different Node version than your machine because the lockfile drifted from what CI actually installs. Pin one Node version in CI config and commit the lockfile, then the mismatch disappears.

the agent assumed CI and local used the same Node version  -  the lockfile had drifted

Steps

1. Print both versions. Run node -v locally, then find the same line in a recent CI log. If they differ, that is the bug. Expected: you see two different version numbers, e.g. local v22.4.0 vs CI v20.18.0.

2. Check what the lockfile says. Look for an engines field or a Volta/pnpm node pin inside package-lock.json or pnpm-lock.yaml, and compare it with the node-version in the CI workflow file. Expected: you find the lockfile asks for one version while the workflow asks for another (or for nothing, which means "latest", which drifts).

3. Pin the version in one place CI trusts. Add the exact version to the workflow's setup step (most teams use a .nvmrc file or the node-version-file option) so every run uses the same one. Expected: the next CI run logs the pinned version in its setup output.

4. Reinstall and commit the lockfile. Delete node_modules, install fresh with the pinned version, and commit the updated lockfile so local and CI resolve the same dependency tree. Expected: a fresh clone plus the pinned version reproduces CI exactly.

5. Rerun the failing test in CI. Expected: green on the same code that failed before, with no test changes.

Use this when

• a test passes locally but fails in CI with no code change between the two
• the agent assumed the environments matched and never checked the Node version
• dependency behavior differs between runs (native modules, optional deps)
• engines in package.json disagrees with the CI workflow

Not for this skill when

• the failure reproduces identically on local and CI (version is not the cause)
• only one environment exists or matters
• the problem is a package version mismatch, not a Node runtime mismatch
• you are debugging a single environment's setup, not a divergence between two

Variant phrasings

• "works on my machine but fails in github actions with a different node version"
• "CI installs different dependencies than local because the lockfile was not committed"
• "lockfile drift between local and CI causing test failures"

Why it happens

CI usually resolves the Node version from the workflow file, not from your lockfile or your laptop. If the workflow says nothing (or says "latest") and the lockfile was generated or hand-edited on a different Node version, the two sides install different trees. Some packages ship different native binaries per Node major version, so a test can pass on one side and explode on the other with no code change at all.

Edge cases

• The workflow may install Node from a container image tag, not a setup action; pin the image tag too.
• npm ci ignores a drifted package.json but still runs on whatever Node the runner has; the lockfile alone does not pin the runtime.
• A developer's globally installed Node can mask the problem locally; always check the project's pinned version, not node -v on PATH.
• Monorepos sometimes pin Node per package; check every workspace that the failing test touches.

Provenance

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

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

Thread query: the agent assumed CI and local used the same Node version - the lockfile had drifted

TL;DR:

Not specified by the original author.

TL;DR

engines allowed Node 16, so CI happily installed a runtime the new dependency does not support. Tighten the range to what you actually support, pin the Node version in CI, and add an .nvmrc so local dev matches.

Error

agent set the engines field too loose  -  CI installed node 16 and the new dep required node 18

Steps

1. Confirm the floor: check the dependency's engines or README for its minimum Node version. Expected output: The dependency requires Node 18 or newer.

2. Set your engines field to the range you actually support (for example 18 and above) in the root manifest and every workspace manifest. Expected output: Node 16 is excluded everywhere.

3. Pin the Node version in CI (workflow node-version, .nvmrc, or volta) to a version inside the range. Expected output: CI installs a known-good Node, not a floating default.

4. Add an engine-strict install (npm config engine-strict) so a wrong Node fails at install time with a clear message. Expected output: Local installs on Node 16 fail fast instead of breaking at runtime.

5. Have the agent check the dependency's Node floor before every major bump and propose the engines change in the same PR. Expected output: The engines field moves with the dependencies it governs.

When to use

• CI installed an older Node than a dependency supports
• The engines field admits versions you do not test
• You are aligning Node versions across manifests and CI

When not to use

• A dependency that genuinely supports the installed Node but fails for other reasons
• Non-Node runtimes; their version floors work differently
• Pinning to a single patch version when a range is fine

Variant phrasings

CI installed node 16 but dependency needs node 18

engines field too permissive, wrong node version in CI

enforce node version with engine-strict

Why it happens

engines is advisory by default: npm warns but installs anyway, and CI images default to whatever Node the image ships. A loose range plus a floating CI image is a standing invitation for the runtime and the dependency to disagree.

Edge cases

• engine-strict can break contributors on slightly older patch versions; keep the range honest, not maximal.
• Some CI providers ignore .nvmrc unless configured; set the version explicitly in the workflow too.
• Native modules built for one Node major can break on another even within the engines range; rebuild on upgrade.

Provenance

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

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

Thread query: agent set the engines field too loose - CI installed node 16 and the new dep required node 18

TL;DR: engines allowed Node 16, so CI happily installed a runtime the new dependency does not support. Tighten the range to what you actually support, pin the Node version in CI, and add an .nvmrc so local dev matches.

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.