Fix npm ERESOLVE Unable to Resolve Dependency Tree

Quick Answer

• Conclusion: The ERESOLVE unable to resolve dependency tree error occurs when npm v7+ detects incompatible peer dependency versions. The quickest fix is npm install --legacy-peer-deps, which bypasses strict peer dependency checking.
• First checks: Verify your npm version (npm -v). If v7+, the strict peer dependency resolver is active. Check which package is causing the conflict by reading the full error output—it lists the conflicting package and its required peer version.
• Minimal fix: Run npm install --legacy-peer-deps to install despite peer dependency conflicts. This is a temporary workaround, not a permanent solution.
• Environment boundary: This error primarily affects npm v7 and later. npm v6 and earlier use a lenient peer dependency resolver and rarely produce ERESOLVE errors. Yarn and pnpm have their own dependency resolution logic and are not directly affected.

What Problem It Solves

Starting with npm v7, the package manager introduced a strict peer dependency resolver. When you run npm install, npm now checks that every installed package's peer dependencies are satisfied by compatible versions already in your project. If a conflict exists—for example, a library requires react@^17.0.0 but your project uses react@18.0.0—npm refuses to install and throws the ERESOLVE error.

This change was intended to prevent runtime errors caused by incompatible library versions. However, it can be overly strict in real-world scenarios, especially when:

• Upgrading a major framework version (e.g., React 17 → 18) while some dependencies haven't caught up
• Working with legacy projects that have unmaintained dependencies
• Rapid prototyping where dependency compatibility isn't the immediate concern

The --legacy-peer-deps flag restores npm v6's behavior, allowing installation to proceed even when peer dependency conflicts exist.

Minimal Working Configuration

The simplest way to bypass the error is to add the --legacy-peer-deps flag to your install command:

BASH
npm install --legacy-peer-deps

This works for both initial installations and when adding new packages:

BASH
# Install all dependencies with legacy peer dep handling
npm install --legacy-peer-deps

# Add a specific package with legacy peer dep handling
npm install some-package --legacy-peer-deps

For repeated use during development, you can set this as an npm config option:

BASH
npm config set legacy-peer-deps true

This makes --legacy-peer-deps the default behavior for all npm install commands in your environment. To revert:

BASH
npm config set legacy-peer-deps false

Root Cause Analysis

The ERESOLVE error occurs because npm v7+ performs a full dependency tree resolution before installation. When it encounters a package that declares a peer dependency on a specific version range, npm checks whether that range is satisfied by the versions already in the tree.

The error message tells you exactly what's wrong. For example:

npm ERR! Found: react@18.0.0
npm ERR! node_modules/react
npm ERR!   react@"18.0.0" from the root project
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from some-package@1.0.0

This means:

• Your project has react@18.0.0 installed
• some-package@1.0.0 declares react as a peer dependency with version range ^17.0.0
• npm cannot find a version of some-package that works with React 18, so it fails

The root cause is always a version mismatch between what a package expects as a peer dependency and what your project actually provides.

Common Errors and Fixes

For each case, the permanent fix involves either:

1. Upgrading the conflicting package to a version that supports your current dependency versions
2. Downgrading your project's dependency to match what the package expects
3. Using npm's overrides field to force a specific version resolution

Production Notes and Security Checks

Do not rely on --legacy-peer-deps in production. This flag is a development convenience, not a production strategy. Here's why:

• Runtime instability: Ignoring peer dependency conflicts can cause subtle runtime errors. A package may use APIs that exist only in a specific version range of its peer dependency. If you bypass the check, you might install incompatible versions that fail at runtime.
• Security audit blind spots: Running npm audit on a dependency tree installed with --legacy-peer-deps may produce inaccurate results. The non-standard dependency resolution can mask real vulnerabilities or report false positives.
• Team friction: If some team members use --legacy-peer-deps and others don't, package-lock.json will diverge, causing merge conflicts and inconsistent environments.
• CI/CD pipeline issues: Avoid using this flag in CI/CD. It masks real dependency problems that should be addressed before deployment.

Recommended production approach: Use npm's overrides field in package.json to explicitly resolve peer dependency conflicts. For example:

JSON
{
  "overrides": {
    "some-package": {
      "react": "$react"
    }
  }
}

This tells npm: when resolving some-package's dependencies, replace its react peer dependency with whatever version of react is in your project root. This permanently resolves the conflict without bypassing all peer dependency checks.

FAQ

Q: Using --legacy-peer-deps caused runtime errors in my app. Why?

A: The flag allows installation of packages with mismatched peer dependency versions. For example, a React component library might require React 17 but you have React 18 installed. The library may use deprecated APIs removed in React 18, causing warnings or crashes at runtime. The permanent fix is to ensure all peer dependency version ranges are actually satisfied, not just bypassed.

Q: What's the difference between --legacy-peer-deps and --force? Which should I use?

A: --legacy-peer-deps only ignores peer dependency conflicts but still respects other dependency constraints. --force is more aggressive—it forces installation despite any conflict, including direct dependency version mismatches, and may overwrite locked versions in package-lock.json. Prefer --legacy-peer-deps as it's safer. Only use --force if --legacy-peer-deps doesn't work and you understand the risks.

Q: How do I permanently fix ERESOLVE without using --legacy-peer-deps every time?

A: Use npm's overrides field in package.json. This lets you force a specific version resolution for a package's peer dependencies. For example, to make some-package accept your project's React version:

JSON
{
  "overrides": {
    "some-package": {
      "react": "$react"
    }
  }
}

After adding this, run npm install normally—no --legacy-peer-deps needed. This is the recommended permanent solution for production projects.