npm ERESOLVE Dependency Tree Error? Every Working Fix

You add a new package, run the install, and npm stops with a wall of red text ending in npm ERR! code ERESOLVE unable to resolve dependency tree. The project worked yesterday, you changed almost nothing, and now npm refuses to install anything at all. It is actually npm protecting you from a version conflict.

This error became common with npm version 7, which treats peer conflicts as errors instead of warnings. The good news is that every part of the error message tells you exactly which packages disagree, and there are clean fixes as well as quick workarounds. This guide explains both, and when to use each one.

Quick Answer

The ERESOLVE error means two packages in your project need incompatible versions of the same peer dependency, and npm cannot build a valid dependency tree. Read the error to find the conflicting packages, then update or downgrade one of them to a compatible version. If you need a temporary workaround, run npm install --legacy-peer-deps to use the older, more relaxed npm behaviour, but treat that as a short-term fix rather than a permanent solution.

What a Peer Dependency Actually Is

Most dependencies are simple: your project needs a library, npm downloads it into node_modules, and your code uses it. A peer dependency is different. It is a package that a plugin or library expects your project to provide at the top level.

React is the classic example. A component library does not bundle its own React; it declares which React versions it supports, and your project must provide one. This prevents two copies of React existing at once.

The problem appears when packages disagree — for example, your project uses React 18 but an older library only supports React 16 or 17. No single React satisfies everyone. Older npm installed anyway with a warning; modern npm stops with ERESOLVE, because silently installing a broken tree caused confusing runtime bugs.

How to Read the ERESOLVE Error Message

The error looks intimidating, but it follows a predictable pattern. Slow down and pull out four pieces of information.

1. Find the line starting with While resolving: — this names the package npm was trying to place when it failed.
2. Find the line starting with Found: — this shows the version already in your tree, for example React 18.2.0.
3. Find the lines mentioning Could not resolve dependency: and peer — these show the version range the other package demands, such as React 16 or 17 only.
4. Read the final suggestion. npm often literally prints the command it thinks you should try, including --force or --legacy-peer-deps, along with a warning about what those options do.

Write down both sides of the conflict before changing anything. Almost every proper fix brings those two sides together. The npm documentation on peer dependencies at docs.npmjs.com explains this behaviour in detail.

Fix 1: Update the Package That Is Behind

The cleanest fix is usually to update the older package, because it was written before the newer framework version existed. A library that only listed React 16 and 17 in its peer range may have released a newer version that officially supports React 18 or 19.

1. Check the installed version with npm list package-name.
2. Check the latest available version with npm view package-name version.
3. Install the newer release with npm install package-name@latest.
4. Run a plain npm install again to confirm the error is gone.

Fix 2: Adjust Your Main Framework Version

Sometimes the package you just upgraded is the one that moved too far. If you updated React, Angular, or another core library to a brand-new major version on release day, many plugins will not support it yet. In that case, holding the core library back one version is the sensible move.

Install the version that your plugins support, for example npm install react@18 react-dom@18 instead of the newest release, and plan the bigger upgrade for when the ecosystem catches up. This is not failure — professional teams delay major upgrades for exactly this reason. If the version conflict is only one of several install headaches on your machine, our broader guide to fixing npm install problems on Windows covers the network, cache, and antivirus causes that can strike at the same time.

Fix 3: Remove the Package That No Longer Fits

Projects collect packages over time, and an ERESOLVE conflict is sometimes a useful signal that a library has been abandoned. If a package has had no release in three years, only supports old framework versions, and blocks every install, the healthiest fix is to replace it.

1. Run npm uninstall package-name.
2. Search for a maintained alternative that offers the same feature and lists support for your framework version.
3. Install the replacement and update the small amount of code that used the old library.
4. Run your tests or start the app to confirm everything still works.

Fix 4: Use –legacy-peer-deps as a Temporary Workaround

The command npm install --legacy-peer-deps tells modern npm to behave like npm version 6: install the packages, ignore peer dependency conflicts, and stop blocking you. It is extremely useful when you need to get a project running today, evaluate an old tutorial project, or unblock a build while a proper fix is planned.

Use it with clear eyes, though. The conflict still exists in your tree. The app may work perfectly — many peer ranges are simply cautious and outdated — or you may meet strange runtime errors that trace back to two packages expecting different versions. If you rely on this flag, note it in your project readme so teammates use the same command, and revisit the real fix later.

If you want every install in one project to use this behaviour automatically, you can add a file named .npmrc in the project root containing the line legacy-peer-deps=true. Only do this for that specific project, not globally, so new projects still get the protection of strict checks.

Fix 5: Understand –force, and Why It Is Riskier

npm also suggests npm install --force. This does not ignore peer rules in the old relaxed way; it forces npm to build a tree even when versions clash, sometimes placing an incompatible version where a package did not expect it. That can produce a node_modules folder that installs successfully but behaves unpredictably at runtime.

In practice, prefer --legacy-peer-deps over --force when you need a workaround, because its behaviour is closer to how projects installed successfully for years. Reserve --force for experiments on a copy of a project, never as the standard install command for a team.

Fix 6: Check for Duplicate or Mismatched Pairs

Some libraries must always move together. React and ReactDOM should be the exact same version. Angular packages should share the same major and minor version. TypeScript version mismatches with certain tooling produce similar tree errors.

• Run npm list and look for lines marked invalid or UNMET PEER DEPENDENCY.
• Align matched packages to the same version in package.json.
• Delete node_modules and reinstall once after aligning versions, so you are testing a clean tree rather than leftovers from earlier attempts.
• Avoid editing package-lock.json by hand. Let npm regenerate it, because one small manual mistake in that huge file creates new conflicts.

For a deeper look at how npm resolves and locks versions, the official npm install documentation explains the algorithm and the role of the lock file in reproducible installs.

Common Mistakes and Useful Tips

• Using –legacy-peer-deps forever without telling anyone. The install works on your laptop and fails in continuous integration. Document the command or save it in the project .npmrc.
• Randomly upgrading everything at once. Running a blanket update changes dozens of versions, and now you cannot tell which change fixed or caused the conflict. Update one side of the conflict at a time.
• Ignoring the package names in the error. The answer is printed in the message. Guessing and reinstalling without reading it wastes the most time.
• Mixing package managers in one project. Installing some packages with npm and others with Yarn or pnpm creates competing lock files and strange trees. Pick one manager per project.
• Tip: upgrade plugins right after a framework upgrade. Most ERESOLVE errors appear in the week after a major version jump, and updated plugins usually follow quickly.

Conclusion

ERESOLVE is not npm being difficult; it is npm refusing to quietly build a tree it knows is inconsistent. Read the error to find the two versions in conflict, then choose the honest fix: update the laggard package, hold the framework back, or replace an abandoned library. Reach for --legacy-peer-deps when you need to move today, but label it as temporary. Handle the conflict properly once, and your installs become boring again — which is exactly what you want from an install command.

Frequently Asked Questions

What does ERESOLVE mean in simple words?

It means npm could not find a set of package versions that all agree with each other. Two packages want different, incompatible versions of the same shared dependency, so npm stops instead of installing a broken combination.

Is –legacy-peer-deps safe to use?

It is widely used and usually works, because it restores the behaviour of older npm versions. It is not a true fix, though — the version conflict remains, so test your app carefully and plan to resolve the underlying mismatch.

Why did this error start appearing after I upgraded npm or Node?

npm version 7 and later enforce peer dependencies strictly, while npm 6 only warned about them. The conflict was probably always present; the newer npm is simply the first version to refuse to ignore it.

Should I delete package-lock.json to fix ERESOLVE?

Deleting the lock file alone rarely fixes a peer conflict, because npm will rebuild the same tree from package.json and hit the same disagreement. Fix the versions first; only regenerate the lock file as part of a clean reinstall afterwards.

What is the difference between –force and –legacy-peer-deps?

--legacy-peer-deps ignores peer conflicts and installs the way old npm did. --force overrides npm checks and can place incompatible versions into the tree, which is more likely to cause odd runtime behaviour, so it is the riskier option.