npm ERESOLVE "unable to resolve dependency tree" - Fix Peer Conflicts

ERESOLVE means npm found a peer dependency conflict it cannot satisfy. The real fix is to resolve the version mismatch - --force just hides it.

What this error means

npm install/npm ci aborts before installing, printing a conflict between a package’s required peer version and what is in your tree.

npm output

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error Found: react@17.0.2
npm error Could not resolve dependency:
npm error peer react@"^18.0.0" from @some/ui@3.1.0

Common causes

A dependency requires a peer version you do not have

A package declares a peer dependency (e.g. React 18) that conflicts with the version your project pins (e.g. React 17).

Lockfile drift

A partially-updated lockfile can encode a tree npm cannot reconcile on a clean install.

How to fix it

Resolve the version conflict (preferred)

Read which peer is required vs what is installed.
Upgrade or downgrade one side so the versions are compatible.
Regenerate the lockfile (rm package-lock.json && npm install) and commit it.

Temporary unblock (use sparingly)

If you must unblock immediately and understand the risk, --legacy-peer-deps ignores peer conflicts. This can produce a runtime-broken tree, so treat it as a stopgap.

Terminal

npm ci --legacy-peer-deps

How to prevent it

Keep dependencies and their peers on compatible major versions.
Commit your lockfile and install with npm ci.
Use tooling (renovate/dependabot) to upgrade peers together.