How do I prevent npm:EBADENGINE in CI?

Pin Node versions with `.nvmrc`, Volta, or CI setup so developers and runners use the same runtime. Check `engines` compatibility when upgrading Node or introducing new dependencies.

How can I manually validate npm:EBADENGINE?

Print the current toolchain versions: `node -v` and `npm -v`. Inspect the package requirements: `npm view @ engines` or check the dependency `package.json` directly. Check whether strict enforcement is enabled: `npm config get engine-strict`.

npm ERR! code EBADENGINE

Fix it fast

Most likely: The package requires a different Node.js or npm version than the one running the install.

Confirm this is your error

Match the output and confirm you are troubleshooting the same failure.

npm ERR! code EBADENGINE
npm ERR! engine Unsupported engine

Check the cause

Run focused checks to identify what is failing in this environment.

node -v
npm -v
npm config get engine-strict
npm view <package>@<version> engines --json

Apply the safe fix

Use the smallest safe change that addresses the confirmed cause.

# Use a Node version that satisfies the package's engines field.
nvm use <supported-node-version>
npm install

# If you use Volta, pin the supported runtime for the project.
volta pin node@<supported-node-version>

Verify it works

Repeat the relevant checks and confirm the original error is gone.

node -v
npm -v
npm install

Avoid unsafe shortcuts

Keep security and data protections in place while troubleshooting.

Do not make engine-strict=false the permanent fix, it can hide a real runtime incompatibility.
Do not widen your own engines field until you have tested the package on that runtime.
Do not upgrade random dependencies before checking which package reported EBADENGINE.

What Does Not Match This Runtime or Platform

npm returned EBADENGINE because the package declares Node.js or npm engine requirements that do not match the versions running your install.

Use a compatible runtime, platform, or published build

Switch to a supported Node version using your version manager or CI image, then reinstall dependencies.

If you control the package, only widen the engines field after confirming the code really supports the newer runtime.

If the failing dependency is outdated, upgrade to a version that supports your current Node or npm.

Why This Runtime or Platform Does Not Match

Usually this comes down to your current Node.js version is older or newer than the package supports, the package also constrains npm itself, and the running npm version is outside that range, or engine-strict or CI policy turns what would be a warning into a failing install.

Prove the Runtime and Published Build Now Line Up

node -v and npm -v now match the package's declared engines range, and re-run the original install and confirm EBADENGINE no longer appears.

Check runtime, platform, and index source

Print the current toolchain versions with node -v and npm -v, inspect the package requirements with npm view <pkg>@<version> engines or check the dependency package.json directly, and check whether strict enforcement is enabled with npm config get engine-strict.

How npm evaluates engine requirements

Packages can declare supported node and npm versions in the engines field of package.json. When your current runtime falls outside that range, npm warns or errors with EBADENGINE, especially when strict engine enforcement is enabled.

Prevent It From Coming Back

To prevent this, pin Node versions with .nvmrc, Volta, or CI setup so developers and runners use the same runtime, and check engines compatibility when upgrading Node or introducing new dependencies.