Node version requirements
How to resolve a Node engine mismatch
Read engines.node ranges, investigate npm EBADENGINE warnings, and align local, CI, and deployment Node versions.
The core answer
An engine mismatch means your Node version falls outside a package's declared engines.node range. npm generally treats engines as advisory for dependencies unless engine-strict is enabled. A warning can still identify an unsupported environment, so align the runtime or choose a release that declares support for your constraints.
Read the declared range against an exact runtime
engines.node uses a version range, while node --version identifies one exact runtime. Compare all parts of that version: a package can require a minimum minor or patch release within the same Node major.
A missing engines.node field leaves the supported runtime unspecified. It does not establish that every Node version works. Likewise, a satisfied range tells you what the publisher declares, rather than proving that your application has passed a runtime test.
{
"name": "example-package",
"engines": {
"node": ">=22.0.0 <23.0.0"
}
}For this synthetic range, Node 22.1.0 satisfies the declaration and Node 20.0.0 does not. This is not the manifest of a real package or a recommendation for a deployment version.
A package install and a supported runtime are different checks
npm can warn about an incompatible engine and still install the dependency. With engine-strict enabled, npm normally refuses incompatible packages; override flags and other package managers can change enforcement. Check the configuration used by the failing command.
Updating only the dependency may leave the deployment runtime behind. Check your version manager, container image, CI setup, hosting settings, and project documentation together so that the same intended runtime reaches production.
What to check next
- 1
Capture the exact versions and warning
Record node --version, npm --version, and the package version named by the warning. Inspect npm config get engine-strict rather than assuming the install policy.
- 2
Inspect the installed release's engines declaration
Use its package.json or query npm view package-name@exact-version engines. Check the release actually present in the lockfile, including transitive dependencies.
- 3
Align the environment and verify the application
Choose a maintained runtime that meets your dependency constraints, or evaluate a compatible package release. Reinstall using the intended lockfile and run your build and tests in the deployment environment.
What a declaration cannot establish
- NPMBot checks a selected package's declaration, not the complete dependency tree or your installed lockfile.
- Operating system, CPU, native addons, and package-manager requirements can impose additional constraints.
- Ignoring an engine warning changes enforcement; it does not add missing runtime APIs.