Node.js version mismatch

What this failure means

The Node.js version installed on the CI runner does not satisfy the engines constraint declared in package.json or the version pinned in .nvmrc.

Symptoms

Faultline looks for one or more of these log fragments:

The engine "node" is incompatible with this module
Required engine node
requires node version
engine: unsatisfied
node: /.*: version
Unsupported engine
error node@
warning: You are using Node.js

Diagnosis

The Node.js version installed on the CI runner does not satisfy the engines constraint declared in package.json or the version pinned in .nvmrc.

Fix steps

1. Identify the required Node.js version from .nvmrc, .node-version, or package.json engines.node.
2. GitHub Actions: set node-version-file: .nvmrc on the actions/setup-node step.
3. GitLab CI: use a versioned image — image: node:20-alpine — matching your .nvmrc.
4. CircleCI: use cimg/node:20.x or pin the version in the .circleci/config.yml executor.
5. Azure Pipelines: use the NodeTool@0 task with a pinned versionSpec.
6. Locally: run nvm use or volta install node to switch to the pinned version.

Validation

• Re-run the local reproduction command after the fix.
• cat .nvmrc && node —version
• nvm use

Why it matters

Package.json engines.node fields and .nvmrc files pin a specific Node.js version for compatibility. If CI installs a different version — often the system default or a recently pinned LTS — builds and tests may fail with syntax errors, missing APIs, or npm engine warnings that are treated as errors.

Prevention

• Commit a .nvmrc or .node-version file so all CI platforms and local environments share one source of truth.
• Configure every CI Node.js setup step to read the version from the pinned file rather than hardcoding a version.
• Run node --version and compare against .nvmrc as an early CI check to catch mismatches before build steps.

Try it locally

cat .nvmrc && node --version
nvm use

How Faultline detects it

Use faultline explain node-version-mismatch to see the full playbook.

faultline analyze build.log
faultline explain node-version-mismatch

Generated from playbooks/bundled/log/build/node-version-mismatch.yaml. Do not edit directly.