npm EBADENGINE "Unsupported engine" - Fix Node Version Mismatch

EBADENGINE means a package declares an engines.node range that the running Node version does not satisfy. By default it is a warning, but with engine-strict it becomes a hard failure.

What this error means

npm prints npm warn EBADENGINE Unsupported engine (or errors, under engine-strict) naming a package, the required Node/npm range, and the version actually in use. The fix is to align the Node version, not to ignore the package.

npm output

npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: 'some-lib@4.0.0',
npm warn EBADENGINE   required: { node: '>=20.0.0' },
npm warn EBADENGINE   current: { node: 'v18.19.0', npm: '10.2.3' }
npm warn EBADENGINE }

Common causes

CI Node version is older than the package requires

A dependency bumped its engines.node to require a newer Node (e.g. >=20) while CI still runs an older line (e.g. 18). The mismatch raises EBADENGINE.

engine-strict turns the warning into an error

With engine-strict=true in .npmrc, npm refuses to install when any engine constraint is unmet, so the warning becomes a failing install.

How to fix it

Pin CI to a supported Node version

Use a Node version that satisfies every dependency’s engines range.

Workflow

# GitHub Actions
- uses: actions/setup-node@v4
  with:
    node-version: 20

Decide on engine-strict deliberately

If you want hard failures on mismatch, keep engine-strict=true and fix the Node version.
If a single transitive package over-declares its range and you have verified compatibility, you can relax strictness rather than downgrade everything - but prefer fixing the version.

How to prevent it

Declare an engines field and keep CI Node in range.
Upgrade Node in CI when dependencies raise their floor.
Use a single source of truth (.nvmrc / setup-node) for the Node version.