Problem
Today a Cloudflare Workers deployment started failing even though the application code had not changed. The clue was near the top of the build log: the build environment was running Node.js 24.
Cloudflare changed the default Node.js version in Workers Builds to Node.js 24.18.0 on July 30, 2026. The build image still includes Node.js 22.23.2, but projects that did not declare a version can begin using the new default automatically.
The exact error depends on the dependency chain. It may appear as an unsupported engine warning, a native package compilation failure, a package-manager incompatibility, or a test that behaves differently under the new major version.
How I Confirmed It
I added a temporary diagnostic command to the build sequence:
node --version
npm --versionI also checked the local version and the version used in other CI systems. Local development and the previous pipeline were on Node.js 22, while Workers Builds had selected Node.js 24.
Fix Option 1: Declare NODE_VERSION
Set NODE_VERSION to a supported Node 22 release in the Workers Builds environment variables. For this build-image release, Cloudflare documents 22.23.2 as included:
NODE_VERSION=22.23.2Use the dashboard's build configuration or the project's supported configuration path, and avoid storing secrets in a committed environment file.
Fix Option 2: Commit a Version File
If the repository should define its build version, add one of the supported files at the project root.
.nvmrc:
22.23.2Or .node-version:
22.23.2Commit only one clear source of truth unless your local tooling requires both. Then rerun the build and verify the selected version in the log.
Why I Pinned Node 22
Pinning Node 22 restored the build, but it is a compatibility bridge rather than a permanent rejection of Node 24. I created a separate upgrade task to run the application, tests, package manager, and native dependencies on Node 24.
Once those checks pass, the version can be upgraded deliberately. That is safer than discovering a major-version incompatibility during an unrelated production deployment.
Preventing This Failure
- Declare the Node major and tested patch version in the repository or build configuration.
- Print runtime versions at the beginning of CI logs.
- Test the next active Node release before the hosting provider changes its default.
- Keep the lockfile committed and review dependency engine requirements.
- Subscribe to the provider's build-platform changelog.
The fix took only a few minutes after identifying the version mismatch. Most debugging time came from assuming that unchanged application code meant an unchanged build environment. Hosted CI images are dependencies too, and they need the same version discipline as packages in package.json.
For another Cloudflare deployment issue, see our Cloudflare API 403 permission fix.