Issue #8544: NODE_VERSION environment variable not taking effect on Cloudflare Pages

Summary

• Status: OPEN
• Created: 2025-03-18
• Updated: 2025-10-30
• Labels: bug
• Reporter: arnewc

Issue Description

User reports that setting NODE_VERSION=22.14.0 as an environment variable in the Cloudflare Pages dashboard does not take effect. The build logs show Node.js 18.17.1 being used instead, causing Next.js builds to fail (requires Node.js >=18.18.0).

Analysis

Root Cause Identified

A community member (@ammarmbe) identified the root cause in the comments:

"I had the same problem, apparently if you have a wrangler config file in your project the env variables will be ignored, even if you don't have them set in the config."

This is a source-of-truth conflict between dashboard-configured variables and local wrangler.toml/wrangler.json configuration. When a wrangler config file exists in the project, dashboard environment variables are not applied.

Maintainer Response

Cloudflare maintainer @petebacondarwin acknowledged this as a known "source-of-truth problem" and referenced an internal ticket DEVX-1279 to add friction when users switch between dashboard and local config.

The maintainer explained the planned solution:

1. Add validation to check difference between current deployment config and wrangler.toml config
2. Require first wrangler.toml-driven deployment to match current config exactly
3. If config doesn't match, fail deployment with instructions to use wrangler pages download config

Work Done

Several related PRs have been merged to address the broader config diffing problem:

• PR #10314 (merged 2025-08-15): "Add information about dashboard configuration differences on deploys"
• PR #10393 (merged 2025-08-29): "Use resolved local config for remote deploy config diffing logic"
• PR #11229 (merged): Enabled experimental-deploy-remote-diff-check flag by default

These improvements help surface config conflicts but don't automatically resolve the NODE_VERSION case.

Workaround

The reporter found a workaround:

"I have successfully specified the Node.js version by creating a .node-version file in my project."

Recommendation: KEEP OPEN

Reasoning

1. Not fixed: The core issue (dashboard vars ignored with wrangler config present) is not fully resolved
2. User impact: Causes confusing build failures with no clear error message
3. Documentation gap: The behavior is not clearly documented, leading to user confusion
4. Maintainer engagement: Internal ticket DEVX-1279 exists but full solution not yet implemented
5. Recent activity: Updated Oct 2025, indicating ongoing relevance

Difficulty: Medium

Implementing proper config merging or validation requires careful consideration of all source-of-truth scenarios.

Suggested Actions

1. Add a warning when deploying with wrangler config file present that dashboard environment variables may be ignored
2. Document this behavior clearly in Cloudflare Pages documentation
3. Complete the DEVX-1279 work to prevent foot-guns when switching between dashboard and local config
4. Consider allowing explicit override of specific variables from dashboard even when wrangler config exists

Suggested Comment

This issue highlights the complexity of having two configuration sources (dashboard and local wrangler config). The core behavior is tracked internally (DEVX-1279), and recent improvements (PR #10314, #10393, #11229) have added better diffing and warnings when deploying.

Workarounds available:

1. Use a .node-version file in your project root (as the reporter discovered)
2. Add vars configuration to your wrangler.toml/wrangler.json with the NODE_VERSION
3. Use wrangler pages download config to sync dashboard settings to local config

Keeping this open to track the need for better documentation and UX around this behavior.