Node runtime pinning boundary when base image updates

Answer

An explicit pin is required for a guaranteed runtime across platform updates. With no pin, Railway can resolve a different Node major/minor when base images or Nixpacks defaults change. If a requested major is removed from the current build image set, Railway does not silently downgrade to a different major; the deployment is expected to fail with an unsupported version rather than fallback.

Precedence during buildpack resolution is: NODE_VERSION environment variable first, then package.json engines.node when NODE_VERSION is unset, then the platform/Nixpacks default. engines.node is a range hint, not a hard lock.

Operators can observe the selected runtime without code changes from the deployment build logs and service variables in the Railway dashboard.

Confirmed facts

• Railway supports pinning Node via the service-level NODE_VERSION environment variable. When set, the build system attempts to use that version for build and runtime.
• package.json engines.node is evaluated by Nixpacks/buildpack detection as a signal for desired Node version. It is used when NODE_VERSION is unset.
• engines.node is a range hint rather than a hard lock.

Likely explanation, not confirmed

• Railway does not silently downgrade a requested major version. If a major requested via NODE_VERSION or engines is absent from the current build image set, the deployment is expected to fail with an unsupported version error rather than fallback to a different major.
• An unset NODE_VERSION allows engines.node to influence selection, but platform image updates can still change the resolved minor/patch within the allowed range.
• Implicit version shift can occur when neither NODE_VERSION nor a restrictive engines.node is set. Platform base image updates or Nixpacks default changes can then resolve the same code to a newer default Node major/minor without code changes.

Steps to verify for this case

1. Open Railway dashboard > Service > Settings > Variables. Note whether NODE_VERSION is present and its value.
2. Open package.json and note engines.node. If NODE_VERSION is unset, this range is the active signal.
3. Open Service > Deployments > latest deployment > Build logs. Look for a Node detection line such as Using node version or Detected Node. That line shows the resolved version without code changes.
4. Compare the resolved version to the variable and engines range to confirm which signal was active.

Assumptions and uncertainty: Behavior is version-sensitive to Railway's build stack and Nixpacks version. Defaults and supported majors change over time. Log wording for Node detection can change with builder updates. engines.node ranges like ^18 or >=18 are permissive and allow minor/patch upgrades when images change.

One diagnostic detail that changes the recommendation: Is NODE_VERSION set to a major-only value e.g. "18" or to a full semver like "18.20.4"? A major-only pin still permits minor/patch movement with image updates, while a full semver pin reduces drift.