How to Fix npm ERR! ERESOLVE Unable to Resolve Dependency Tree

The npm ERR! ERESOLVE unable to resolve dependency tree error means npm found conflicting peer dependency requirements between packages in your project. npm 7+ made peer dependency resolution stricter — packages that quietly installed alongside each other in npm 6 now fail. Here’s every fix explained.

Understanding the Error

npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: my-app@1.0.0
npm ERR! Found: react@18.3.1
npm ERR! node_modules/react
npm ERR!   react@"^18.0.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.8.0 || ^17.0.0" from some-old-package@2.1.0
npm ERR! node_modules/some-old-package

Reading this error: Your project uses React 18. some-old-package requires React 16 or 17 as a peer dependency. npm refuses to install because it sees this as a conflict.

Fix 1: –legacy-peer-deps (Safest Quick Fix)

npm install --legacy-peer-deps

This reverts npm to v6 behavior — installs packages without enforcing peer dependency conflicts. The package might work fine with the newer peer version even though it declares an older range.

When to use: When you’ve tested the combination works, the package hasn’t been updated to declare new React/Vue/Angular peer versions, and you trust the dependency won’t actually break.

Persist for all future installs:

# .npmrc file (commit this to repo)
legacy-peer-deps=true

Fix 2: –force (Last Resort)

npm install --force

What it does: Forces installation even with conflicting versions, potentially installing multiple versions of the same package. More aggressive than --legacy-peer-deps.

When to use: Only when --legacy-peer-deps doesn’t work and you’ve verified the combination is safe. --force can create subtle runtime bugs from mismatched versions.

Fix 3: Upgrade the Conflicting Package

# Check if a newer version supports your React/Node version
npm info some-old-package peerDependencies

# Try installing a specific version
npm install some-old-package@latest

# Or check if there's an RC/beta with support
npm install some-old-package@next

This is the right fix when the package has been updated. Always check for a newer version before reaching for legacy-peer-deps.

Fix 4: overrides Field (npm 8.3+, Most Correct Approach)

// package.json
{
  "dependencies": {
    "some-old-package": "2.1.0",
    "react": "^18.0.0"
  },
  "overrides": {
    "some-old-package": {
      "react": "^18.0.0"
    }
  }
}

The overrides field tells npm to force a specific version of a nested dependency. This is the most correct solution — you’re explicitly saying “use React 18 for this package too” rather than silently ignoring the conflict.

For Yarn (resolutions field):

// package.json
{
  "resolutions": {
    "some-old-package/react": "^18.0.0"
  }
}

Fix 5: Find an Alternative Package

If a package hasn’t been maintained and doesn’t support current peer versions, it’s often a sign to find a better-maintained alternative:

# Check last publish date
npm info some-old-package

# Check GitHub for issues/PRs about the newer React version
# Look for: forks, alternatives, or community maintained versions

A package last published 2+ years ago with open issues about React 18 compatibility is likely abandoned. Search npm for modern alternatives with active maintenance.

Decision Tree

ERESOLVE error
    ↓
Is there a newer version of the conflicting package?
    YES → npm install package@latest
    NO ↓
Does the package actually work with your version (test it)?
    YES → Use --legacy-peer-deps or overrides in package.json
    NO ↓
Is there an actively maintained alternative?
    YES → Switch packages
    NO → Use --legacy-peer-deps and monitor for issues

Common Scenarios and Fixes

# Scenario: Create React App with React 18
npx create-react-app my-app  # old CRA doesn't support React 18
# Fix: Use Vite instead
npm create vite@latest my-app -- --template react-ts

# Scenario: Storybook + React 18
npx sb init  # older Storybook versions conflict
# Fix: Use current Storybook
npx storybook@latest init

# Scenario: Old Redux package conflicts
# Fix: upgrade to Redux Toolkit (official recommendation)
npm install @reduxjs/toolkit react-redux

# Scenario: Next.js conflicting peer deps
# Fix: usually just --legacy-peer-deps works; Next.js team is aware

Frequently Asked Questions

Q: Is –legacy-peer-deps safe?
A: Usually yes, especially when the conflict is about peer version ranges being conservative (e.g., peer says React 16-17 but works fine with 18). Always test after using it. The risk is subtle runtime incompatibilities that only appear in edge cases.

Q: Why did npm change peer dependency behavior?
A: npm 7+ made peer dependency resolution strict to prevent silent version conflicts that caused hard-to-debug runtime errors. It’s more correct behavior — the tradeoff is more explicit resolution required.

Q: Should I use npm overrides or –legacy-peer-deps?
A: overrides in package.json is more explicit and documents the decision. --legacy-peer-deps is quicker but implicit. For production projects, prefer overrides so the override is visible in code review.

Q: This error appeared after upgrading Node.js — is that related?
A: Node.js upgrades often bring newer npm versions with stricter peer dep resolution. Downgrading Node isn’t the solution — use overrides or --legacy-peer-deps and update your dependencies to versions compatible with the newer Node/npm.

Q: How do I prevent this in new projects?
A: Start with modern tooling (Vite, Next.js 14+, latest CRA alternatives) that have up-to-date peer declarations. Avoid packages with poor maintenance histories. Use npm outdated quarterly to stay current.

Conclusion

npm ERESOLVE errors are usually resolved by: (1) upgrading the conflicting package to a version that supports your framework version, (2) using overrides in package.json for a documented fix, or (3) --legacy-peer-deps as a quick temporary fix. Avoid --force unless nothing else works — it can create runtime version conflicts. The best long-term fix is keeping dependencies updated so version conflicts don’t accumulate.