ErrorVaultHQ

Solved Error

How to Fix: npm ERR! ERESOLVE unable to resolve dependency tree

Quick Fix

In most cases this is caused by npm 7+'s stricter peer dependency checking. Try this first: 1. Re-run the install with the legacy flag. Type npm install --legacy-peer-deps instead of a plain npm install. This tells npm to use the older, more relaxed peer-dependency resolution from npm 6 and below. 2. If that still fails, delete node_modules and package-lock.json, then run npm install --legacy-peer-deps again for a clean install.

What this error means

ERESOLVE is npm's dependency resolution error. It occurs when npm cannot resolve a dependency tree while trying to install packages, because it is unable to find a compatible version of a package that meets the requirements specified by the dependent packages. This npm install error appears when npm cannot find compatible versions of packages that work together, creating a dependency conflict that blocks installation. This almost always shows up because of peer dependencies. Peer dependencies are packages that aren't directly installed but are expected to exist in your project, and when different packages require different versions of the same peer dependency, conflicts arise. This is especially common with React and React Native libraries requiring specific React versions. If your project worked fine before and suddenly broke, it is usually a tooling or version change, not something you did wrong. This typically happens when you upgrade npm from version 6 to 7 or higher, update a package that introduces new peer dependencies, or when a dependency updates its own requirements. In npm v7+, npm install will fail by default when it encounters conflicting peerDependencies, whereas this was not an issue in npm versions 3 through 6, which used to ignore peerDependencies when building the package tree.

Step-by-Step Guide

Fix 1: Use the --legacy-peer-deps flag

  1. 1Run the install with the flag. This is the fastest, most commonly confirmed fix for this exact error. Use npm install --legacy-peer-deps in place of your normal install command. The --legacy-peer-deps flag tells npm to ignore peer dependencies and to proceed with the installation anyway, which was the default behavior in npm versions 4 through 6.
  2. 2Installing a single package. If the error appears only when adding one specific module, append the flag to that command instead, e.g. npm install react --legacy-peer-deps.
  3. 3Make it permanent for one project (recommended over global). Add a .npmrc file with legacy-peer-deps=true to the specific project that needs it. This also fixes the error during automated builds or CI/CD (for example Heroku), since adding an .npmrc file with legacy-peer-deps=true makes the platform apply the same dependency resolution behavior you may have used locally with --legacy-peer-deps.
  4. 4Avoid setting it globally. You can run npm config set legacy-peer-deps true globally, but this isn't recommended as it applies to all projects on your machine.

Fix 2: Clean reinstall (clear cache, lockfile, and node_modules)

  1. 1Delete node_modules and package-lock.json. Stale or corrupted cache and lockfile data can also trigger false conflicts. If the error persists, try to delete your node_modules and package-lock.json (not package.json) files, then re-run npm install.
  2. 2Clear the npm cache. A corrupted cache can lead to issues, so clear the npm cache with the appropriate command.
  3. 3Reinstall. Run npm install again, and add --legacy-peer-deps if the plain install still fails: if you still get an error, delete your node_modules and package-lock.json, rerun the npm install command, and restart your development server.
  4. 4Restart terminal and development server. Restart your terminal/dev server afterward, since restarting your terminal and development server after running the commands can help clear lingering state.

Fix 3: Identify and fix the actual version conflict (most stable long-term fix)

  1. 1Read the error output carefully. Flags hide the problem rather than solve it. While flags like --legacy-peer-deps and --force offer quick fixes, the most stable solution remains updating packages to compatible versions. It lists the package that was 'Found' with its version, and the conflicting 'peer' requirement from another package — this tells you exactly which two packages disagree.
  2. 2Check the conflicting package's supported versions. Run npm info package-name peerDependencies to see what version range it actually supports.
  3. 3Update the outdated package. Often a newer release of the conflicting package already supports your current setup; check with npm show package-name versions and npm outdated.
  4. 4Adjust your own package.json. If you're intentionally on a newer version (for example TypeScript or React) that a dependency doesn't yet support, you can pin your project to a compatible version instead, or wait for the dependent package to update.
  5. 5Use npm ls to trace conflicts. Use the npm ls command to find out which packages are causing the conflict, and look for any warnings or error messages in the output.
  6. 6Advanced: use overrides/resolutions. For stubborn transitive dependency conflicts, add an overrides block to package.json (or aliased installs) to force a single version across the tree; this is best reserved for cases where updating packages directly isn't possible.

Fix 4: As a last resort, use --force

  1. 1Understand the risk first. The --force flag ignores all conflicts and warnings during installation, while --legacy-peer-deps specifically uses npm 6's less strict peer dependency resolution — legacy-peer-deps is safer since force bypasses all safety checks.
  2. 2Only use in development, not production. Treat npm install --force as a temporary unblock, then follow up with Fix 3 to properly align versions.
  3. 3Test thoroughly afterward. Ignoring peer dependencies can lead to unexpected behavior in the application, so use this option as a last resort and thoroughly test the application afterward.

When to get further help

Platform-specific builds (Heroku, Vercel, Docker, CI/CD): add the legacy-peer-deps setting to an .npmrc file committed to the repo so the build server applies it automatically, rather than relying on a local flag. Monorepo or workspace setups: the conflict may originate in a shared dependency used by multiple workspace packages — check each package.json individually with npm ls. If the package itself is abandoned or incompatible with your framework version (e.g. no version supports your current React/Angular/TypeScript version), consider searching for a maintained alternative library instead of forcing the install. Still stuck? Search the specific package's GitHub Issues page for the exact peer dependency named in your error message — maintainers often document the required companion version there.

Sources:

Heads up: this guide was drafted with AI assistance from the real sources listed below, and structured by our team for clarity. It may not cover every possible cause — if it doesn't fix your issue, let us know and we'll take a closer look. See how we create our fixes.

Was this fix helpful?

Related Error Fixes