agent debugged with node 20 while CI pins node 18 — the failure wa

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

If convex deploy fails on Node 20+ with fetch failed and retry loops while older Node versions work, upgrade the convex npm package to 1.25.2 or later, which works around the Node network-family autoselection race.

Steps

1. If convex deploy fails on Node 20+ with fetch failed and retry loops while older Node versions work, upgrade the convex npm package to 1.25.2 or later, which works around the Node network-family autoselection race. On versions before that, run deploys with NODE_OPTIONS=--no-network-family-autoselection. In CI, pin both the Node major version and the convex package version together so a base-image bump cannot silently reintroduce the failure.

Expected: The fix shipped in convex@1.25.2, and the reporter confirmed it resolved the deploy on Node 22 and in GitHub Actions.

When to use

You are seeing this: In CI, pin both the Node major version and the convex package version together so a base-image bump cannot silently reintroduce the failure. Use this skill when you run into "Convex deploy fails on Node 20+ Linux: upgrade convex past 1.25.2".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

Versions mentioned in the source: 1.25.2. If you are on something much newer or older, the details may have shifted.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: GitHub issue get-convex/convex-js#52 (closed, 13 comments): convex deploy failed on Linux with Node 20+ with fetch failed and repeated request retries during schema validation, while Node 18/19 worked. The maintainer traced it to a Node.js 20 regression in network family autoselection (Happy Eyeballs): if the connection took longer than about 250ms it was dropped. The fix shipped in convex@1.25.2, and the reporter confirmed it resolved the deploy on Node 22 and in GitHub Actions. Immediate workaround on affected versions: NODE_OPTIONS=--no-network-family-autoselection npx convex deploy.

Verified resolution: If convex deploy fails on Node 20+ with fetch failed and retry loops while older Node versions work, upgrade the convex npm package to 1.25.2 or later, which works around the Node network-family autoselection race. On versions before that, run deploys with NODE_OPTIONS=--no-network-family-autoselection. In CI, pin both the Node major version and the convex package version together so a base-image bump cannot silently reintroduce the failure.

Source URL: https://github.com/get-convex/convex-js/issues/52