pnpm ERR_PNPM_UNSUPPORTED_ENGINE - Fix Node Version Mismatch in CI

pnpm enforces engines ranges. ERR_PNPM_UNSUPPORTED_ENGINE means the running Node (or pnpm) version falls outside a required engines.node range, failing the install when strict engine checking applies.

What this error means

pnpm install fails with ERR_PNPM_UNSUPPORTED_ENGINE, naming the package, the wanted Node range, and the current version. It is pnpm’s stricter counterpart to npm’s EBADENGINE.

pnpm output

ERR_PNPM_UNSUPPORTED_ENGINE  Unsupported engine

The wanted version of Node.js: >=20
Your Node.js version: 18.19.0
The wanted package: some-lib@4.0.0

Common causes

CI Node older than the package requires

A dependency’s engines.node demands a newer Node than CI runs, and pnpm enforces it.

engine-strict / use-node-version mismatch

A strict engine setting, or a pinned use-node-version that differs from the package requirement, triggers the failure.

How to fix it

Run a supported Node version

Pin CI Node to satisfy every dependency’s engines range.

Workflow

- uses: actions/setup-node@v4
  with:
    node-version: 20
# pnpm can also manage it:
# package.json -> "engines": { "node": ">=20" }

Align engine settings intentionally

Keep strict engine checking on and fix the Node version (preferred).
If pnpm’s use-node-version is set, ensure it satisfies dependency engines.
Set your own engines.node so the requirement is explicit.

How to prevent it

Keep CI Node aligned with engines ranges.
Bump CI Node when dependencies raise their floor.
Use a single source of truth for the Node version.