Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

yarn install refuses a package because of its engines field

Errorerror <package>@<version>: The engine "node" is incompatible with this module. Expected version ">=18". Got "16.20.0"

Short answer

Yarn 1 compares the node version you run with the engines field of every package it installs and stops on a mismatch. The clean fix is a Node version inside that range. If you accept the risk, yarn install --ignore-engines skips the check, and yarn config set ignore-engines true makes it permanent.

  • Applies to Yarn 1.22, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Compare the Node version you run with the range the failing package asks for. The error line names both.

    node -v
    yarn --version
  2. 2Match what you see, then jump to its fix

    1. 1Expected version shows a range such as ">=18" and Got shows your older or newer Node.Your Node.js is outside the package's engines rangeFix
    2. 2A single old package sets a narrow engines range, but your build works on your Node.You must install with a Node outside the range, and accept the riskFix
    3. 3The failing package is your own project, or a workspace in it.Your own package.json sets an engines range your machine does not matchFix

What does the error look like?

  • error <package>@<version>: The engine "node" is incompatible with this module. Expected version ">=18". Got "16.20.0"
  • error Found incompatible module.

Cause 1 of 3

Your Node.js is outside the package's engines range

1Check

Yarn checks engines against the current node version and Yarn's own version. The check follows semver.

yarn install

2Fix

Install a Node version inside the range with nvm and switch to it. nvm install accepts a version number, an alias such as node, or lts.

nvm install 22
nvm use 22
yarn install

3Verify

The command finishes without the incompatible-module error.

node -v && yarn install

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 3

You must install with a Node outside the range, and accept the risk

1Check

The check only reads package metadata; it does not test that the code runs. Re-run the failing install and note which package complains.

yarn install

2Fix

Skip the check for one command, or set it in Yarn's config so CI does the same.

yarn install --ignore-engines
# permanent:
yarn config set ignore-engines true

3Verify

Run your tests; a passing install is not proof the package works on this Node.

yarn test

Confirmed by classic.yarnpkg.com

Did this fix it?

Cause 3 of 3

Your own package.json sets an engines range your machine does not match

1Check

The engines field declares which versions of node a package must be used with, and Yarn reads it for your project too.

grep -n -A3 '"engines"' package.json

2Fix

Widen the range to what you support, then pin the same Node for the team in .nvmrc.

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

3Verify

Install on the Node version you target.

yarn install

Confirmed by classic.yarnpkg.com

Did this fix it?

How do I stop it coming back?

  • Put the supported Node range in engines and a matching .nvmrc in the repository.
  • Use the same Node version in CI as on your machine.
  • Do not leave ignore-engines on globally; use it per command.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.