Convex deploy fails on Node 20+ Linux: upgrade convex past 1.25.2

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