package.json "engines" node/npm Unmet - Fix Self-Declared Version Gate in CI

Your package.json can declare an engines range for node and npm. With engine-strict enabled, installing your own project on a runner whose node/npm falls outside that range fails - the gate you set on yourself is what blocks the build.

What this error means

An install of your own project fails (or warns) with EBADENGINE naming your package and your declared engines range, because the CI runner’s node or npm version is outside what you specified. The constraint is self-imposed in your package.json.

npm output

npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: 'my-app@1.0.0',
npm warn EBADENGINE   required: { node: '>=20', npm: '>=10' },
npm warn EBADENGINE   current: { node: 'v18.19.0', npm: '9.8.1' }
npm warn EBADENGINE }

Common causes

CI node/npm is below your declared engines range

You declared engines.node/engines.npm to encode a requirement, but the CI runner provisions an older version, so the gate you set is unmet.

engine-strict makes the gate fatal

With engine-strict=true, an unmet engines range is a hard install failure rather than a warning - including for your own package’s range.

How to fix it

Provision node/npm inside your declared range

Pin the CI runner to versions that satisfy your own engines field.

Workflow

# .nvmrc / setup-node to satisfy engines.node
- uses: actions/setup-node@v4
  with:
    node-version: 20
# upgrade npm if engines.npm requires it:
npm install -g npm@10

Reconcile the declared range with reality

Confirm the engines.node/engines.npm ranges reflect what you actually support.
Align .nvmrc/setup-node and the CI npm version to that range.
Bump the engines floor and the CI versions together when you drop old support.

How to prevent it

Keep CI node/npm within your declared engines range.
Use .nvmrc + setup-node as one source of truth.
Update engines and CI versions in lockstep.