npm install refuses with ERESOLVE and a peer dependency conflict
npm error code ERESOLVEShort 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.
Fix it fast
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 peerDependencies2Match what you see, then jump to its fix
- 1
Could 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
The conflicting package is not in your package.json but deep inside another dependencyOne transitive package pins a version you cannot change from outsideFix - 3
The 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
- 1
What does the error look like?
npm error code ERESOLVEnpm error ERESOLVE unable to resolve dependency treenpm error While resolving: my-app@0.0.0npm 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 peerDependencies2Fix
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@latest3Verify
npm completes and the tree has no invalid entries.
npm lsConfirmed by docs.npmjs.com
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-package2Fix
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-packageConfirmed by docs.npmjs.com
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-deps2Fix
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-deps3Verify
The app builds and its tests pass; the lockfile shows the versions you expect.
npm run build
npm testConfirmed by docs.npmjs.com
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 fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack 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 fixBack end
Angular build says it cannot resolve '@angular/localize/init'
Can't resolve '@angular/localize/init' in '/usr/src/app/src'
The build imports @angular/localize, and that package is not in node_modules.
2 causes, each with a fixBack end
The command npm run build -- --prod exited with code 1 (Angular)
The command "npm run build -- --prod" exited with code 1
Exit code 1 only says the build failed; the real message is above it.
2 causes, each with a fix