`npm ERR! ERESOLVE` Is Usually What Happens When Your Dependencies Disagree and Your Installer Finally Stops Pretending It Can Guess the Right Answer

Why this error matters: ERESOLVE is not npm being dramatic. It is npm finally telling you that two packages want incompatible worlds and that blind installation would just hide the problem until runtime.

One of the most common frontend and Node setup failures now starts with some variation of:

npm ERR! ERESOLVE unable to resolve dependency tree

The first bad instinct is to treat it like a random installer tantrum and solve it with:

npm install --force

or:

npm install --legacy-peer-deps

Those flags can unblock you, but they also make it easier to install a dependency graph that does not actually agree with itself. If the project later behaves strangely, you end up debugging symptoms instead of the real mismatch.

What the error usually means

Most ERESOLVE failures come from peer dependency conflicts.

A package is basically saying:

1. “I work with React 18”
2. another package says “I require React 19”
3. your app currently has one of those, not both

npm used to be looser about this. Modern npm is more willing to stop and show you the conflict instead of papering over it.

Start by reading the actual conflict

Run the install command again and look for the two packages in conflict. Then inspect your tree:

npm ls react
npm ls typescript
npm ls eslint

If the problem is package metadata rather than the currently installed tree, inspect declared ranges:

cat package.json

or, if you want one field fast:

npm pkg get dependencies
npm pkg get devDependencies

The goal is to answer:

1. which package is imposing the restrictive peer range
2. whether your root package is pinned too high or too low
3. whether a newer compatible version of the conflicting package exists

The clean fix order

1. Check whether one side simply needs an update

npm outdated

If the plugin or framework package has a newer version that supports your current stack, upgrade that first.

For example:

npm install some-plugin@latest

2. If the root dependency is the outlier, align it

If a plugin ecosystem is still on React 18 and you pulled React 19 into a project that is not ready, stepping back may be cleaner than forcing everything through.

npm install react@18 react-dom@18

3. Delete stale install state if the tree has already been churned

rm -rf node_modules package-lock.json
npm install

This does not solve a real version conflict by itself, but it clears old lockfile state once you have chosen a proper version combination.

When --legacy-peer-deps is acceptable

Use it only when:

1. you understand the conflict
2. the package combination is known to work in practice
3. you need a temporary unblock for local testing

Example:

npm install --legacy-peer-deps

That is a tactical move, not a design decision.

A simple resolution workflow

npm ls
npm outdated
npm install package-causing-conflict@latest
rm -rf node_modules package-lock.json
npm install

If that still fails, align the framework version with the plugin ecosystem instead of piling on installer flags.

Final recommendation

Treat ERESOLVE as dependency information, not installer hostility. Read the conflicting peer ranges, decide which package set should win, then rebuild the tree cleanly. The real fix is usually version alignment, not --force.

Sources

• npm package.json documentation
• npm install documentation