Fix npm ERESOLVE Dependency Tree Error

Learn how to spot, diagnose, and fix the common npm ERESOLVE dependency‑tree error. Follow a step‑by‑step guide that covers peer‑dependency conflicts, lockfile issues, and how to use overrides and clean installs to resolve them.

Recognizable Condition

When you run npm install in a project that uses npm v7 or newer, you may see a non‑zero exit code and a log entry that looks like this:

npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!   While resolving: my‑app@1.0.0
npm ERR!   Found: react@18.2.0
npm ERR!   node_modules/react
npm ERR!     react@"^18.0.0" from the root project
npm ERR!   Could not resolve dependency:
npm ERR!   peer react@"^17.0.0" from react‑compat@1.2.3

The error lists the package that caused the conflict and the two incompatible versions.

Root Causes & Diagnostic Table

Cause	Why It Happens	What the Log Says
Unmet peer dependency	npm v7+ treats peer dependencies as hard requirements.	"peer react@\"^17.0.0\" from react‑compat"
Lockfile pinning	A `package-lock.json` was committed after an upgrade that changed the peer range.	"Found: react@18.2.0" vs. required "^17.0.0"
Transitive conflict	A dependency of a dependency declares an incompatible peer.	"peer pkg‑X@\"^2.0.0\"" from pkg‑Y@1.0.0"

Ordered Checks

Print the tree for the offending package.
```
npm ls react
```
Look for the line that shows the version npm resolved and the parent that requested it. This tells you whether the conflict originates at the root or a transitive dependency.
Inspect package.json and package-lock.json.
Search for the package name in both files. Compare the peerDependencies in the package that caused the error with the version that npm resolved. Pay attention to the ^ and ~ range operators.
Check npm version.
```
npm --version
```
Only npm v7+ will surface this error. For older npm, the same situation would silently install the peer.
Determine if the conflict is direct or transitive.
If the offending package appears under node_modules as a direct dependency, you can edit it. If it is only a transitive dependency, you may need to use overrides or report the issue.

Fixes Tied to Findings

Missing peer added as a direct dependency.
When npm reports a missing peer, install it explicitly:
```
npm install react@18 --save
```
Replace react@18 with the version that satisfies all peer ranges.
Adjust the range in package.json.
If a dependency declares a narrow peer range, broaden it if you control the package:
```
{"peerDependencies": {"react": "^18.0.0"}}
```
Then run npm install again.
Use overrides for transitive conflicts (npm v9+).
Add an overrides section to force a version:
```
{"overrides": {"react-compat@1.2.3": {"react": "^18.0.0"}}}
```
Run npm install to apply the override.
Clean install.
When lockfile pins a bad version, delete the lockfile and node_modules, then reinstall:
```
rm -rf node_modules package-lock.json
delete
npm install
```
After editing package.json, this regenerates a compatible lockfile.
Temporary suppression.
If you need to ship a build quickly, run:
```
npm install --legacy-peer-deps
```
Beware: this may install incompatible peer versions and should not be used in CI pipelines.

Escalation Criteria

If the conflict originates in a package you do not maintain, and the above fixes do not resolve it, file an issue on the maintainer’s repository.
When the conflict involves a long‑standing major version mismatch that cannot be reconciled, consider pinning the entire dependency tree to a known working set using npm ci --prefer-offline after locking the versions.
For projects that must run on multiple npm versions, maintain a .npmrc that forces legacy-peer-deps=true only for legacy environments, while CI uses the default strict mode.

Practical Verification

After applying a fix, run npm install again and confirm the exit code is 0 and the log no longer contains ERESOLVE.
Run npm ls react to verify the resolved version matches the one declared in package.json.
Commit the new package-lock.json and run npm ci in a clean clone to ensure reproducibility.

Limitations & Caveats

Overriding peer dependencies can mask real compatibility problems; use it sparingly.
Deleting package-lock.json changes transitive versions and may introduce new bugs. Always test thoroughly after a clean install.
Legacy‑peer‑deps is a blunt tool that bypasses the peer dependency check entirely; it is not a long‑term fix.

Diagnosing and Fixing npm ERR! ERESOLVE Unable to Resolve Dependency Tree