Blog
6 min read

npm EBADENGINE "Unsupported engine": What It Means and How to Fix It

npm warn EBADENGINE Unsupported engine means a package wants another Node version. When to ignore it, what engine-strict does, and how to switch Node.

npm warn EBADENGINE Unsupported engine means a package in your project declares, in its engines field, that it needs a different version of Node.js (or npm) than the one you're running. By default it is only a warning and the install still completes. The real fix is to run the Node version the package asks for, usually by switching with nvm or fnm. It becomes a hard npm error code EBADENGINE only when engine-strict is turned on.

What the message looks like

The warning version, which is what most people see:

npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: 'some-tool@5.0.0',
npm warn EBADENGINE   required: { node: '>=22' },
npm warn EBADENGINE   current: { node: 'v20.18.0', npm: '10.8.2' }
npm warn EBADENGINE }

The error version, when engine-strict is enabled:

npm error code EBADENGINE
npm error engine Unsupported engine
npm error engine Not compatible with your version of node/npm: some-tool@5.0.0
npm error notsup Not compatible with your version of node/npm: some-tool@5.0.0
npm error notsup Required: {"node":">=22"}
npm error notsup Actual:   {"npm":"10.8.2","node":"v20.18.0"}

Three things to read:

  1. package: which package is complaining (some-tool@5.0.0).
  2. required: the version range it declares (node: '>=22').
  3. current / Actual: what you're running (v20.18.0).

So the message above says: "some-tool 5 wants Node 22 or newer, and you're on Node 20."

Where the requirement comes from: the engines field

Package authors put this in their package.json:

"engines": {
  "node": ">=22"
}

The npm package.json docs describe it as advisory: unless the user has set engine-strict, it only produces warnings. The ranges use the same syntax as dependency versions (see semantic versioning explained).

npm checks every package it installs, including your own project's package.json if it has an engines field.

Is it safe to ignore?

Sometimes, but not as a habit.

  • It's often fine when the gap is small and the package raised its minimum for housekeeping reasons (for example, dropping a Node version that has reached end-of-life).
  • It's risky when the package relies on newer Node features. You may get a crash at runtime, such as SyntaxError, is not a function, or a missing built-in module, rather than at install time. That's harder to debug than the warning.
  • Watch for it in production. If your laptop runs Node 22 but your server or Docker image runs Node 20, the warning appears only on the server, and so do the crashes.

The practical rule: if you see EBADENGINE for a package your app uses at runtime, match the Node version. If it's a dev tool that works fine, you can live with it for a while, but plan the upgrade.

Fix 1: switch to the Node version the package needs

With nvm (macOS, Linux, WSL)

If you don't have it yet, see what is nvm. Then:

nvm install 22
nvm use 22
node --version

To pin the version for the project so everyone uses the same one, add a .nvmrc file:

echo "22" > .nvmrc

According to the nvm README, nvm use, nvm install and nvm which read the version from .nvmrc when you don't pass one. So a teammate only has to run nvm install and nvm use in the project folder.

With fnm (also works on Windows)

fnm is a faster alternative that reads both .nvmrc and .node-version files:

fnm install 22
fnm use 22

With a version file in the project, fnm use --install-if-missing picks it up. If you set up your shell with fnm env --use-on-cd (as the fnm README shows), fnm switches automatically when you cd into the folder.

After switching

Reinstall so any packages with native code are rebuilt against the new Node version:

rm -rf node_modules
npm install

The node_modules explained post covers why native modules care which Node they were built with.

Fix 2: use an older version of the package

If you can't upgrade Node yet (a hosting platform that only offers an older version, for example), install the last version of the package that supported yours. Check what each version required:

npm view some-tool versions
npm view some-tool@4 engines

Then pin it:

npm install some-tool@4

This is a reasonable stopgap. Note it down, because older versions stop receiving fixes.

Turning the warning into an error on purpose: engine-strict

If you'd rather fail fast than discover a mismatch at runtime, enable engine-strict for the project in an .npmrc file next to package.json:

engine-strict=true

The npm config docs say that with this set, npm "will stubbornly refuse to install (or even consider installing)" any package that claims to be incompatible with the current Node version. Combined with an engines field in your own package.json, it stops anyone installing with the wrong Node.

The flip side: if someone has engine-strict=true in their user-level ~/.npmrc and you're seeing a hard error you didn't expect, check that file. npm config get engine-strict tells you the current value.

You may also see --force suggested. The config docs confirm it overrides engine checks even when engine-strict is on. That's a sledgehammer: it also changes how npm handles other conflicts. Avoid it as a fix for EBADENGINE.

The CI and Docker angle

EBADENGINE often shows up only in CI or a container, because those environments pick their own Node version.

GitHub Actions. Make CI read the same version file as your laptop, so there's one source of truth:

steps:
  - uses: actions/checkout@v7
  - uses: actions/setup-node@v7
    with:
      node-version-file: '.nvmrc'
  - run: npm ci
  - run: npm test

The setup-node docs list .nvmrc, .node-version and package.json among the accepted files. For more on CI setup, see GitHub Actions CI basics.

Docker. The Node version comes from the base image tag. If your Dockerfile says FROM node:20-slim and a dependency needs Node 22, you'll get the warning during npm ci in the build. Change the tag to match your .nvmrc:

FROM node:22-slim

Pin a major version rather than node:latest, so a new release can't silently change your runtime. Our production Dockerfile for Node walks through a full example.

Hosting platforms. Many platforms read engines.node from your own package.json to decide which Node to run. Check your host's docs. Declaring it is a cheap way to keep local, CI and production aligned.

Summary

  • EBADENGINE means a package's engines range doesn't include your Node or npm version.
  • By default it's a warning. With engine-strict=true it's an error.
  • Best fix: install and use the required Node version (nvm, fnm) and pin it in .nvmrc.
  • Can't upgrade Node? Pin an older version of the package for now.
  • Make CI and Docker use the same version as your machine.

If the install fails with a dependency conflict instead, that's a different error: see npm ERESOLVE.

EasySpawn detects Node projects and runs them with Claude Code on a persistent cloud server, so installs, builds and version fixes all happen in the one environment your app actually runs in. See how it works or join the waitlist.

Related: Semantic Versioning Explained: What 2.4.1 Actually Means · What Is nvm? Install and Switch Node.js Versions the Easy Way · What Is node_modules? (And When to Delete It) · Set Up CI With GitHub Actions in Ten Minutes

Keep reading