## 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.

```text
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