How to fix npm ERR! code EBADDEVENGINES npm ERR! devEngines incompatible in npm

npmINTERMEDIATEMEDIUMUpdated Dec 5, 2025· 211 views

EBADDEVENGINES occurs when your development environment doesn't match the requirements specified in a package's devEngines field. Update your Node.js or npm version to match the project requirements.

Quick fix

Fixes EBADDEVENGINES

node --version
npm --version
  1. Check your current Node.js and npm versions
  2. Update npm to match project requirements
  3. Update Node.js using a version manager
  4. Clear npm cache and reinstall dependencies
npm — error
node --version
npm --version
npm ERR! code EBADDEVENGINES
npm ERR! devEngines incompatible

What this error means

The EBADDEVENGINES error occurs when npm detects that your current development environment (Node.js version, npm version, or package manager) doesn't match the requirements specified in the `devEngines` field of a package's package.json. The `devEngines` field is a newer npm feature that allows package authors to enforce specific development tools and versions for contributors. This error is stricter than a warning and indicates a version mismatch that npm considers incompatible. The `devEngines` field supports constraints for the runtime (Node.js), package manager (npm/pnpm/yarn), OS, CPU architecture, and libc version.

Typical symptoms

  • npm install fails immediately with 'npm ERR! code EBADDEVENGINES' before downloading any packages
  • Error message shows 'Invalid semver version X does not match Y for packageManager' or similar
  • The error appears even when using --force or --legacy-peer-deps flags
  • Project works fine for some team members but fails for others with different environments
  • CI/CD pipelines fail during npm install despite working locally

Common causes

  1. Your npm version doesn't match the version specified in devEngines.packageManager
  2. Your Node.js runtime version is incompatible with devEngines.runtime requirements
  3. The devEngines field uses an exact version constraint instead of a range, making the check overly strict
  4. Package manager mismatch when devEngines specifies pnpm or yarn but you're using npm
  5. Outdated npm version that doesn't properly validate devEngines format
  6. The devEngines field has invalid syntax or uses unsupported semver ranges

How to fix "npm ERR! code EBADDEVENGINES npm ERR! devEngines incompatible"

1Check your current Node.js and npm versions

First, identify what versions you're currently running:

bash
node --version
npm --version

Then check what the project requires by looking at package.json:

bash
grep -A 10 'devEngines' package.json

Compare your versions with the requirements.

2Update npm to match project requirements

If your npm version is outdated, update it globally:

bash
npm install -g npm@10.9.2

Or use a version range that matches the project:

bash
npm install -g npm@^10.9.0

Verify the update:

bash
npm --version
3Update Node.js using a version manager

Use a Node version manager like nvm to switch to the required Node version:

bash
# Using nvm
nvm install 22.0.0
nvm use 22.0.0

# Using fnm
fnm install 22.0.0
fnm use 22.0.0

Create or update a .nvmrc file to lock the version for your team:

bash
echo '22.0.0' > .nvmrc
4Clear npm cache and reinstall dependencies

After updating your tools, perform a clean install:

bash
# Remove node_modules and lock files
rm -rf node_modules
rm -f package-lock.json

# Clear npm cache
npm cache clean --force

# Reinstall dependencies
npm install
5If the problem persists, adjust devEngines constraints

If you can modify the project's package.json, consider making devEngines more flexible:

Before (too strict):

json
{
  "devEngines": {
    "packageManager": {
      "name": "npm",
      "version": "10.9.0",
      "onFail": "error"
    }
  }
}

After (uses semver ranges):

json
{
  "devEngines": {
    "packageManager": {
      "name": "npm",
      "version": "^10.9.0",
      "onFail": "warn"
    }
  }
}

Change onFail from error to warn to make the check non-blocking.

6Verify compatibility with your CI/CD environment

If the error only occurs in CI/CD pipelines, update your CI configuration. For GitHub Actions:

yaml
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: '22'
      cache: 'npm'
  - run: npm install

Ensure CI installs the Node and npm versions specified in devEngines.

Advanced notes

The devEngines field is a relatively new npm feature (introduced in npm v10.7.0) that distinguishes between engines (constraints for end users) and devEngines (constraints for developers). There's a known bug where simply having a devEngines field present disables the older engines field checks. The onFail option can be set to 'error' (blocks installation), 'warn' (shows warning but continues), or 'ignore' (no validation).

Frequently asked questions

What does "EBADDEVENGINES" mean?
json. The devEngines field is a newer npm feature that allows package authors to enforce specific development tools and versions for contributors. This error is stricter than a warning and indicates a version mismatch that npm considers incompatible.
How do I fix "EBADDEVENGINES"?
EBADDEVENGINES occurs when your development environment doesn't match the requirements specified in a package's devEngines field. Update your Node.js or npm version to match the project requirements.
What causes "EBADDEVENGINES"?
Your npm version doesn't match the version specified in devEngines.packageManager Your Node.js runtime version is incompatible with devEngines.runtime requirements The devEngines field uses an exact version constraint instead of a range, making the check overly strict
Is the "EBADDEVENGINES" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading