npm ERR! code ERESOLVE — unable to resolve dependency tree

The exact error string

A typical ERESOLVE failure from npm install looks like this:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: my-app@1.0.0
npm ERR! Found: react@18.2.0
npm ERR! node_modules/react
npm ERR!   react@"^18.2.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^17.0.0" from react-some-widget@2.1.0
npm ERR! node_modules/react-some-widget
npm ERR!   react-some-widget@"^2.1.0" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

Read it bottom-up. The Could not resolve dependency block is the key: react-some-widget@2.1.0 declares a peer of react@"^17.0.0", but the root project has react@18.2.0 installed. 18 does not satisfy ^17, so npm cannot build one tree that makes both happy.

What is a peer dependency?

A peer dependency is a package that a library expects you to provide, rather than bundling its own copy. Plugins do this constantly: a React component library declares react as a peer so it shares the single React instance in your app instead of shipping a second one. The library says “I work with React 17,” and it is your job to have a compatible React installed.

The trouble starts when two packages disagree about which version you should provide. One peer wants React 17, your app uses React 18, and there is no single version that satisfies both ranges. That irreconcilable overlap is exactly what ERESOLVE reports.

Why npm 7+ throws this when npm 6 did not

This error is new to most people because npm changed its behavior. npm 6 quietly ignored peer dependency conflicts — it would print a warning at most and install whatever it could, leaving you with a tree the package authors never tested. npm 7 (bundled with Node 16) began treating unmet peer dependencies as hard errors and stops with ERESOLVE rather than installing a tree it considers incorrect.

The change was deliberate. npm 7 introduced strict peer dependency resolution specifically to prevent broken dependency trees — the kind that installed cleanly under npm 6 but then failed at runtime with cryptic symptoms like Cannot find module, duplicate-React bugs, or mismatched type definitions. Surfacing the conflict at install time, when it is cheap to fix, is the entire point: a failed install is far better than a green install that crashes in production.

npm 8, 9, and 10 — shipped with Node 18, 20, and 22 — all keep this strict behavior. So if the error appeared right after you upgraded Node or switched machines, the conflict was almost certainly there all along; your older npm simply never told you about it.

Fix 1: Align the versions (the correct fix)

The only fix that yields a genuinely correct tree is to make the versions compatible. Read the error to see which range is unmet, then resolve it one of three ways:

• Upgrade the conflicting package — check whether a newer version of react-some-widget supports React 18. This is the best outcome.
• Downgrade the package that is too new — if you must keep react-some-widget@2.1.0 and it truly needs React 17, downgrade React (rarely worth it for a single widget).
• Find a maintained alternative — a peer stuck on an old major version is often a sign the package is unmaintained.

# See if a newer version supports your React
npm view react-some-widget peerDependencies
npm view react-some-widget versions --json

# Upgrade to a version whose peer range matches React 18
npm install react-some-widget@latest

Fix 2: --legacy-peer-deps (the common workaround)

When the dependency simply has not updated its peer range yet — but you know it works with your version — tell npm to install the way npm 6 did and skip the peer check entirely:

npm install --legacy-peer-deps

# Make it the default for this project (local + CI behave the same):
# create or edit .npmrc in the project root
echo "legacy-peer-deps=true" >> .npmrc

This is the right tool when a maintainer is slow to widen a peer range that is, in practice, compatible. The trade-off: you are installing a combination of versions nobody officially tested, so verify your app still runs. If you add it to .npmrc, leave a comment explaining why — treat it as temporary, not a permanent silencer.

Fix 3: overrides for buried transitive conflicts

Sometimes the conflict is not in a package you installed directly, but deep in a sub-dependency you do not control. npm 8.3+ lets you force a resolved version with an overrides block in package.json:

{
  "overrides": {
    "react-some-widget": {
      "react": "$react"
    },
    "some-deep-dep": "1.4.0"
  }
}

The "react": "$react" syntax pins the nested peer to whatever version your root project uses. Use overrides surgically — you are overruling what a package author declared, so confirm the forced version actually works. (Yarn calls this resolutions; pnpm uses pnpm.overrides.)

Fix 4: --force (last resort)

npm install --force overrides all conflicts, not just peer ones, and will happily install a duplicated or mismatched tree. It is broader and riskier than --legacy-peer-deps and can produce a node_modules that is genuinely broken at runtime. Reach for it only when nothing else works and you are prepared to debug the result.

# Targeted: ignore ONLY peer dependency conflicts (prefer this)
npm install --legacy-peer-deps

# Heavy-handed: override ALL conflicts (can break your tree)
npm install --force

Which fix should I use? (decision flow)

Work top-down. Each step is one question; if the answer is yes, take the green action and stop. If no, drop to the next question. The last resort — --legacy-peer-deps — is only for when nothing above it is possible.

Common scenarios

Most ERESOLVE errors come from a handful of framework upgrades. If your conflict matches one of these, jump straight to the recommended action:

ERESOLVE in CI but not locally

A frequent variant: npm install works on your laptop but CI fails with ERESOLVE. The usual cause is a stale package-lock.json — your local node_modules was built before the conflict, while CI installs from scratch. If CI uses npm ci (which it should), it installs strictly from the lockfile and surfaces the conflict immediately.

The fix is to resolve the conflict locally, delete node_modules and package-lock.json, run a fresh npm install, and commit the regenerated lockfile. Never “fix” CI by hand-editing the lockfile — regenerate it from a clean install so the resolution is reproducible.

Debugging checklist

• ✓ Read the Could not resolve dependency block — it names the package and the unmet peer range
• ✓ Run npm view <package> peerDependencies to confirm what the package actually requires
• ✓ Check for a newer version of the conflicting package that supports your framework version
• ✓ If the peer range is merely stale, install with --legacy-peer-deps and verify the app runs
• ✓ For a buried sub-dependency, add an overrides block (npm 8.3+) rather than --force
• ✓ After fixing, delete node_modules + package-lock.json, reinstall clean, and commit the new lockfile