Maaz Zindani

Loading the index…

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

npm install refuses with ERESOLVE and a peer dependency conflict

Errornpm error code ERESOLVE

Short answer

ERESOLVE means two packages in your tree ask for incompatible versions of a shared peer dependency, and npm 7 or newer refuses to guess. Read which package wants which range, then move that package to a compatible version. Use overrides for one stubborn clash, and --legacy-peer-deps only when you accept the risk.

  • Applies to npm 10, Node.js 22, Angular 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the three lines under the error: what npm was resolving, what it found, and which peer range does not match. Then see who depends on the clashing package.

    npm ls @angular/core
    npm view some-library peerDependencies
  2. 2Match what you see, then jump to its fix

    1. 1Could not resolve dependency: peer @angular/core@"^x" from <library>, while you have a newer majorA library supports an older major version of your frameworkFix
    2. 2The conflicting package is not in your package.json but deep inside another dependencyOne transitive package pins a version you cannot change from outsideFix
    3. 3The clash is a peer range that is stricter than what the library really needs, and no newer release existsYou need to move on while a library catches upFix

What does the error look like?

  • npm error code ERESOLVE
  • npm error ERESOLVE unable to resolve dependency tree
  • npm error While resolving: my-app@0.0.0
  • npm error Could not resolve dependency: peer @angular/core@"^17.0.0" from some-library@2.1.0

Cause 1 of 3

A library supports an older major version of your framework

1Check

Compare the peer range the library declares with the version you installed. peerDependencies state which host versions the library works with.

npm view some-library versions --json | tail -n 5
npm view some-library@latest peerDependencies

2Fix

Install a release of the library whose peer range includes your version. If no release does, the library has not caught up; look for its maintained fork or an issue that tracks support, rather than forcing it in.

npm install some-library@latest

3Verify

npm completes and the tree has no invalid entries.

npm ls

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 3

One transitive package pins a version you cannot change from outside

1Check

Find the path that pulls it in, then confirm that the newer version is safe for you before overriding.

npm ls conflicting-package

2Fix

Declare an override in the root package.json. npm applies overrides from the root project only. Nested keys limit the override to one parent.

{
  "overrides": {
    "some-library": {
      "conflicting-package": "^2.0.0"
    }
  }
}

3Verify

Reinstall and check that only the version you chose is in the tree.

rm -rf node_modules package-lock.json
npm install
npm ls conflicting-package

Confirmed by docs.npmjs.com

Did this fix it?

Cause 3 of 3

You need to move on while a library catches up

1Check

npm 7 and newer install peers and fail on conflicts. The legacy flag makes npm ignore peerDependencies entirely, as npm 3 to 6 did, so npm stops enforcing the contract the library declared.

npm config get legacy-peer-deps

2Fix

Use the flag for the one install, test the app, and write down why. Do not set it globally. Do not reach for --force: it also allows other protections to be bypassed.

npm install --legacy-peer-deps

3Verify

The app builds and its tests pass; the lockfile shows the versions you expect.

npm run build
npm test

Confirmed by docs.npmjs.com

Did this fix it?

How do I stop it coming back?

  • Upgrade a framework major only after checking that your main libraries list it in their peer range.
  • Commit package-lock.json and install with npm ci in CI so the tree stays the same.
  • Keep overrides in package.json with a comment in your commit message, and remove them when the library catches up.

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.