## TL;DR
EBADENGINE means the package declares it needs a newer node than the one running. Check the engines field, then upgrade node (nvm, the CI image, or the Dockerfile) to a version inside the required range. Downgrading the package is the fallback when node cannot move.

## Error

```text
npm warn EBADENGINE  -  the new dep requires a newer node  -  how to fix
```

## Steps

1. Read what the package demands: npm view [package name] engines.
   Expected output: An engines object stating the required node range, for example node 18 or newer.
2. Check what you have: node -v, and check .nvmrc, the CI image tag, or the Dockerfile base.
   Expected output: You see the gap, for example node 16 installed while the package needs 18 or newer.
3. Move node into range: install the needed major with nvm, update .nvmrc, and bump the CI image or Dockerfile base.
   Expected output: node -v reports a version inside the engines range.
4. Reinstall and rerun the build or tests: npm install then the project's test command.
   Expected output: EBADENGINE is gone and the suite passes on the new runtime.
5. If node cannot move (managed platform), pin the dependency back to the last version supporting your node: npm install [package name]@[last good version].
   Expected output: The warning disappears because the installed version's engines match.

## When to use

- npm prints EBADENGINE after adding or bumping a dependency
- A dependency's engines field requires a newer node than CI or the dev machine runs
- You need to decide between upgrading node and pinning the package back

## When not to use

- EBADENGINE appears for a package you already plan to remove; remove it instead
- The warning is about npm itself rather than node; that is an npm upgrade, not a node upgrade
- You are already on the required node and something else is failing; look at the actual error

## Variant phrasings

### npm warn EBADENGINE unsupported engine on a new install
The general shape: any fresh install can surface it when the lockfile pulls a newer transitive dependency.

### The new dep requires node 18 but CI runs node 16
For the CI-specific case; the fix lives in the workflow file or the container image, not in package.json.

### How to handle EBADENGINE without upgrading node
Pin the offending package to its last compatible major; document the pin so a future agent does not bump past it.

## Why it happens

Packages declare supported runtimes in engines, and npm warns when the running node falls outside it. It is a warning, not an error, but the package may genuinely use newer syntax or APIs, so ignoring it risks runtime crashes. Upgrades surface it when a new major of a dependency raises its minimum node.

## Edge cases

- Transitive dependencies can trigger EBADENGINE too; inspect the named package, not just your direct deps.
- nvm in CI needs the right shell init; a .nvmrc alone does nothing if the job never activates it.
- Some platforms pin node per app; check the platform's node settings before editing Dockerfiles.

## Provenance

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