npm's "ERESOLVE unable to resolve dependency tree" and peer dependency conflicts

What it is

npm error code ERESOLVE (npm 10.6 and later; npm ERR! code ERESOLVE in npm 7 to 10.5) comes from npm's own dependency resolver. npm's documentation of the package.json format describes peerDependencies and the overrides field used to adjust them; since npm 7, peer dependencies are installed automatically rather than merely warned about, which means npm must now find a single version of each package that satisfies every peer range in the tree at once. ERESOLVE means it could not: your project or one of its direct dependencies declares a peerDependencies range on a package, and some other dependency in the tree needs a version outside that range. Conflicts deep in the tree are by default resolved with only an ERESOLVE overriding peer dependency warning; --strict-peer-deps turns those into failures too.

Why it matters

The error is not a bug report about a broken package by itself; it is npm stating a genuine constraint conflict that existed before npm 7 too, just silently. Working around it without understanding which two requirements actually collide risks installing a tree that does not satisfy what one of the packages expects at runtime, even though the install itself succeeds.

How to apply

• Diagnose: read the full error block, not just its first line - npm prints Found: x@version (what is currently resolved) followed by one or more Could not resolve dependency: peer x@"range" from y@version lines that name exactly which package needs which range, and from where. npm ls <package> --all after that shows every place in the tree depending on it.
• Fixes, least to most invasive:
  1. Update the conflicting package(s) to versions whose peer ranges actually overlap - often the real fix, since the conflict frequently reflects one dependency being genuinely behind the others.
  2. If one package's peer range is simply stricter than reality (it declares a narrow range but is known to work with the newer major in use), pin just that nested resolution with the overrides field in package.json (npm 8.3+), documented alongside peerDependencies, rather than relaxing checking for the whole tree.
  3. Unsafe escape hatch: npm install --legacy-peer-deps, documented as an npm-install option, restores npm 6's behaviour of not automatically installing or strictly checking peers - it works, but it stops npm from verifying peer expectations anywhere in the tree, not just for the one conflict at hand.
  4. npm install --force goes further, installing even over other conflicts npm detects; treat it as a one-off last resort, not something checked into CI as a default, since the resulting tree may not actually satisfy what a package expects when it runs.
• Not a fix: deleting node_modules and package-lock.json and reinstalling - when the declared ranges conflict, npm fails the same way, and the lockfile's pinned versions are lost.

Pitfalls

• Reaching for --force before reading which two packages actually conflict, which then has to be diagnosed anyway once something breaks at runtime.
• Committing --legacy-peer-deps as a permanent CI flag, which lets new, unrelated peer conflicts accumulate silently afterward.