This EBADDEVENGINES error occurs when your Node.js version doesn't match the devEngines.runtime requirement. Update Node.js using nvm or fnm to match the project's specified version.
Fixes EBADDEVENGINES
node --version
npm --versionnode --versionnpm --versionnpm ERR! code EBADDEVENGINESnpm ERR! devEngines.runtime incompatible with current node version
The npm EBADDEVENGINES error occurs when a package's devEngines.runtime specification doesn't match your current Node.js version. The devEngines field is a newer npm feature that specifies development environment requirements to ensure all developers working on a project use compatible tooling. When npm detects a mismatch between the required runtime version in devEngines.runtime and your installed Node.js version, it throws this error. This differs from the traditional engines field: engines is advisory during package installation, while devEngines is stricter and enforces consistency across development environments.
First, verify what versions you're currently running:
node --version
npm --versionNote the exact versions returned. You'll need these to compare against the devEngines requirement.
Open your package.json and locate the devEngines section:
{
"devEngines": {
"runtime": {
"name": "node",
"version": "^24.4.0",
"onFail": "download"
}
}
}The version field uses semantic versioning. The "^" means "compatible with 24.4.0 or higher, but less than 25.0.0".
Install the correct Node.js version using nvm (Node Version Manager):
# Install nvm if you don't have it (macOS/Linux)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
# Install the required Node version from devEngines
nvm install 24.4.0
# Use that version for the current shell
nvm use 24.4.0
# Verify the change
node --version
npm --versionAfter installation, delete node_modules and package-lock.json, then reinstall.
If you're using pnpm, yarn, or other package managers, you may need additional configuration. Check if onFail is set to 'download' in devEngines:
cat package.json | grep -A 5 devEnginesIf onFail is 'download', the package manager should automatically fetch the correct Node version. If not working, update your package manager:
npm install -g npm@latestIf your package.json has both engines and devEngines fields, ensure both specify compatible versions:
{
"engines": {
"node": ">=24.4.0 <25.0.0",
"npm": ">=10.8.0"
},
"devEngines": {
"runtime": {
"name": "node",
"version": "^24.4.0"
}
}
}If you need engine-strict enforcement, create an .npmrc file:
echo "engine-strict=true" >> .npmrcAfter installing the correct Node version, clean install your dependencies:
# Remove cached dependencies and lock files
rm -rf node_modules package-lock.json
# Clear npm cache
npm cache clean --force
# Fresh install
npm install
# Verify there are no remaining errors
npm list --depth=0Known npm bug: The mere presence of the devEngines field in package.json disables all checks from the traditional engines field, even if devEngines is empty. For monorepo setups using workspaces, devEngines requirements are checked at the workspace root level, so all projects must use compatible Node versions. Docker users should pin their base image to match devEngines.runtime (e.g., FROM node:24.4.0-alpine instead of FROM node:latest). The onFail action requires npm 9.5.0+ and only works with supported package managers.