npm ERESOLVE: The Real Fix for Dependency Tree Errors

Cause #1: Peer Dependency Conflicts (The Usual Suspect)

This is the big one. You run npm install and get a wall of red text ending with ERESOLVE unable to resolve dependency tree. The culprit here is almost always a package that expects a specific version of another package — usually React, Angular, or a UI library — but you've already got a different version installed.

For example, you install some-ui-kit which lists react@^17.0.0 as a peer dependency, but your project already has React 18. npm sees the conflict and refuses to proceed. It's not being stubborn — it's trying to prevent two versions of React from coexisting, which would break hooks and context.

Here's the thing: in older npm versions (6 and below), this would just print a warning and move on. Since npm 7, it's a hard error. So if you're on a legacy project that was built with npm 6, this is a daily annoyance.

The fix: First, actually look at the error. It tells you exactly which package is conflicting. Don't just blindly run --force — you might end up with a broken dependency tree that'll bite you later.

npm install --legacy-peer-deps

That flag tells npm to ignore peer dependency conflicts and install anyway — same behavior as npm 6. It's the safest quick fix because it doesn't change your package.json. But it's a band-aid, not a cure. Every time you run a fresh install, you'll need that flag again.

If you want a permanent solution, you can set it in your project config:

npm config set legacy-peer-deps true

That writes to your .npmrc file, so future installs pick it up automatically. Just be careful — this is a global setting if you run it without --location=project, so add that to keep it local:

npm config set legacy-peer-deps true --location=project

This works for most cases. But sometimes the conflict is because your package versions are genuinely out of sync — which brings us to cause #2.

Cause #2: A Package Version Mismatch in Your Project

Sometimes the ERESOLVE error isn't about external peer dependencies — it's about your own project's package.json. You've got two packages that require different versions of the same library, and npm can't hoist both.

Say you have package-a requiring lodash@^4.17.0 and package-b requiring lodash@^3.10.0. npm 7+ will throw ERESOLVE because it can't nest them the way npm 5 did. It's a feature, not a bug — nested node_modules caused all sorts of runtime chaos.

The fix: Update the offending package to a version that supports the same dependency range. Check npm's website for the latest version and compare its peer dependencies. Usually the package maintainers already fixed this in a newer release.

npm view some-package peerDependencies

That command shows you what peer dependencies a package expects. If the version you have is old, update it:

npm install some-package@latest

If updating isn't an option — maybe it's a legacy package that hasn't been touched in years — you can use npm overrides to force a specific version. This is a bit of a sledgehammer, so use it only when you know what you're doing.

"overrides": {
  "lodash": "^4.17.21"
}

Put that in your package.json and run npm install again. npm will now use that version for all sub-dependencies, even if they requested an older one. Just test your app thoroughly — forcing a major version jump can break things silently.

This scenario shows up a lot when you're mixing packages that were built for different eras of the same framework. I've seen it with React Router versions and Webpack loaders more times than I care to count.

Cause #3: Corrupted Cache or node_modules

Less common, but it happens. Your node_modules directory gets into a weird state — maybe a failed install left half-extracted packages, or your npm cache has stale metadata. The error message might be the same, but the root cause is different.

The fix: Start by cleaning up, but don't go nuclear immediately. First, try clearing the npm cache:

npm cache clean --force

Then delete node_modules and package-lock.json:

rm -rf node_modules package-lock.json
npm install

That's the standard reset. If it still fails, check your npm version — I've seen bugs in specific npm versions that cause false ERESOLVE errors. Update to the latest stable:

npm install -g npm@latest

One more thing: if you're using a Node version manager like nvm, make sure you're on a Node version that's actually compatible with the packages you're installing. Node 22 might be too new for some packages that were built when Node 16 was cutting edge. That's not an ERESOLVE-specific issue, but it can cause dependency resolution to fail in weird ways.

If you're still stuck after all this, you can try npm install --force — yes, the flag I told you not to use blindly. But at this point you've ruled out peer dep conflicts and version mismatches, so forcing it is a reasonable last resort. Just know that it might mask a real issue, so keep an eye on runtime errors.

Quick Reference

That's the whole playbook. Start with --legacy-peer-deps — it'll solve 80% of cases without breaking anything. If not, move down the list. And if you're working with a team, add the .npmrc setting to your repo so everyone gets the same behavior — nothing worse than a dev who can't reproduce your bug because they have different npm configs.