npm ERR! ERESOLVE unable to resolve dependency tree

This error often pops up when npm (version 7+) encounters conflicting dependencies. As a developer, I ran into it while creating a new React project – npm complained it “could not resolve dependency” and stopped the install. In short, npm now treats peer-dependency conflicts as errors (whereas npm 6 only gave warnings). Let’s break down why this happens and how to fix it.

Why am I seeing this error?

Starting with npm 7 (shipped in Node 15+), peer dependencies must be resolved at install time. If your project has one version of a library but a dependency requires a different version, npm throws the ERESOLVE error. For example, in one case I had React 18 in my app but a plugin required React 17. Npm reported:

As OneUptime’s guide explains, this means “npm cannot satisfy both requirements” and suggests you fix the upstream conflict or retry with --force or --legacy-peer-deps. In other words, npm is telling us exactly what to do: either align the versions or ignore the conflict.

What are peer dependencies?

A peer dependency is a way for a package to declare which version of another package it expects. In npm 7+, peer dependencies are automatically installed only if the version matches exactly. If there’s a mismatch, npm 7+ halts with ERESOLVE. The OneUptime guide puts it simply: **“You have React 18 installed” and “some-package requires React 17”, so npm fails. In contrast, older npm (v6) would have just warned about this.

How can I fix this error?

There are a few common approaches – some quick and dirty, others more robust. I always prefer to solve the actual conflict if possible, but in a pinch you can bypass npm’s strict check. Here are the main solutions I’ve used:

1. Use --legacy-peer-deps. This flag tells npm to ignore peer dependency conflicts, restoring npm 7’s behavior to the old npm 6 approach. In practice, run:

1. or set it permanently with:

1. This is usually enough to let the install complete. In my React project, setting npm config set legacy-peer-deps true finally allowed npx create-react-app to finish.
2. Use --force. Alternatively, npm install --force will override all dependency conflicts and proceed. This can be useful if --legacy-peer-deps still fails. However, use with caution: --force ignores even more checks and can leave you with a broken install. As one expert notes, --legacy-peer-deps is safer because it “still enforces other safeguards” and merely skips peer-dep checks, whereas --force skips everything. In other words, --force may solve the immediate error but could cause harder-to-debug issues later.
3. Update conflicting packages. The best long-term fix is to resolve the version mismatch. Check if one of your dependencies has a newer version that supports your current setup. For example, if some-package wants React 17 but you need React 18, see if some-package@latest supports React 18. You can run:

1. and then update it in your package.json (e.g. to ^3.0.0) and reinstall. In my case, updating a plugin to a React-18-compatible release eliminated the error entirely. If no update exists, you might need to find an alternative package. As one npm community expert put it, “Try updating the library to a React 18 compatible version… If no update exists, find an alternative library”.
2. Downgrade Node/npm (workaround). As a last resort, you could use an older Node version (e.g. Node 14) that bundles npm 6. Npm 6 will install despite peer conflicts (only warnings appear). This effectively sidesteps the strict check. It’s not ideal for the long run, but it’s a quick workaround if you’re in a pinch and can’t upgrade the conflicting packages yet.

Can I use Yarn instead?

Some developers switch to Yarn, since Yarn v1 doesn’t enforce strict peer checks the same way. In practice, running yarn add <package> often completes without an ERESOLVE error. However, Yarn has its own quirks and you may need to migrate your lockfile. If you’re stuck, using Yarn can be a quick alternative, but be aware you’re changing package managers. There’s no harm in trying npm install --legacy-peer-deps first, since it mimics Yarn’s relaxed behavior without switching tools.

Summary

To wrap up, npm ERR! ERESOLVE unable to resolve dependency tree means npm detected conflicting package versions. The short-term fixes are to bypass it (--legacy-peer-deps or --force) or downgrade npm. The long-term fix is to update your dependencies so they agree. In my experience, setting npm config set legacy-peer-deps true solved my immediate issue, but I ultimately updated the conflicting library so everything installs cleanly. I hope this helps you get past that frustrating ERESOLVE error – happy coding!