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:
- package: which package is complaining (
some-tool@5.0.0). - required: the version range it declares (
node: '>=22'). - 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
enginesrange doesn't include your Node or npm version. - By default it's a warning. With
engine-strict=trueit'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
npm ETARGET "No matching version found": What It Means and How to Fix It
npm error code ETARGET, No matching version found, means your registry has no such version. Check typos, unpublished versions, .npmrc scopes and cache.
Git "error: object file is empty": How to Recover a Corrupted Repository
Git error object file is empty or loose object is corrupt after a crash or full disk? Back up .git, delete empty objects, re-fetch, and check with git fsck.