npm error code EBADENGINE after upgrading a dependency during node migration

TL;DR

Install and switch to a Node version inside the required range with your version manager (nvm, fnm, or volta), then reinstall. EBADENGINE means a dependency (or your own engines field) declares it needs a different Node than the one running npm. Matching the runtime to the requirement is the fix; overriding the check just moves the crash to runtime.

npm error code EBADENGINE
npm error engine Unsupported engine
npm error notsup Required: {"node":">=20"}
npm error notsup Actual:   {"node":"v18.20.0","npm":"10.8.0"}

Steps

1. Read the error's Required vs Actual lines, and run node -v to confirm. Expected: you see the gap (e.g. required >=20, actual v18).

2. Install the needed Node with your version manager, e.g. nvm install 20, then switch to it (nvm use 20). Expected: node -v prints a version inside the required range.

3. Record it: update .nvmrc (or the volta pin in package.json) so the next person and CI get the right version automatically. Expected: the repo declares the Node it needs.

4. Delete node_modules and reinstall with npm install. Expected: the install completes with no EBADENGINE.

5. If CI enforces engine-strict and you cannot change Node there, fix the CI image. Do not bypass the check to make CI green. Expected: CI runs the same Node the repo declares.

Use this when

• EBADENGINE appears during install while a Node migration is in progress
• The error shows Required/Actual node lines
• A dependency upgrade pulled in a higher engines requirement
• CI fails installs that pass locally (different Node versions)

Not for this skill when

• EBADENGINE appears only as a warning (npm warns by default; it errors only with engine-strict). Note it and move on.
• The engine mismatch is on npm itself (upgrade npm)
• A package requires a Node newer than anything released (wait for the release or replace the package)
• The failure is ERESOLVE or EINTEGRITY (different error codes, different fixes)

Variant phrasings

• npm ERR code EBADENGINE unsupported engine
• npm error notsup required node version
• EBADENGINE after node upgrade
• npm install fails engines field node version

Why it happens

Packages declare supported Node ranges in their engines field. With engine-strict enabled (common in CI configs and project templates), npm turns a mismatch into a hard error instead of a warning. During a Node migration the running Node lags (or leads) what the newly upgraded dependency requires, and every install fails until the runtime matches.

Edge cases

• Overriding with --engine-strict=false or --force lets the install finish, but the package may use APIs your Node lacks. Prefer matching the version.
• overrides can pin an older dependency that supports your Node, if upgrading Node is not an option.
• Check .nvmrc, the Dockerfile, and the CI config together. Fixing one while another pins the old version just moves the error.
• Version-manager shims can disagree about which Node is active. Verify with which node that the binary is the one you think.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_bNqkwdqMcBnGJ0NASuIIpw