ERESOLVE unable to resolve dependency tree: peer dependency conflict reporting

Question

ERESOLVE unable to resolve dependency tree
When pnpm encounters a peer dependency conflict during resolution, it emits the error ERESOLVE unable to resolve dependency tree. This message signals that the resolver cannot satisfy the declared peer constraints across the dependency graph.
The current documentation does not specify a consistent policy for handling such conflicts. Some releases fail immediately, others provide a warning, and a few attempt automatic resolution. This ambiguity complicates reproducible builds, especially in monorepo environments where multiple packages declare overlapping peer dependencies.
To design reliable CI pipelines, we need to understand the intended behavior and how it evolves across pnpm versions. The following questions remain unanswered:

What is pnpm’s official policy for peer dependency conflicts in the latest stable release?
Do newer releases (v8.x and v9.x) introduce deterministic conflict‑resolution strategies, or does the behavior remain version‑dependent?
How can we programmatically detect and react to these conflicts to ensure consistent installation outcomes?

Muntasir · Answer

What pnpm Does When a Peer Conflict Happens
When pnpm cannot satisfy a peer dependency constraint, it aborts the install and prints the error ERESOLVE unable to resolve dependency tree. This is the default, strict‑peer‑resolution policy that has been in place since pnpm 7.x and remains the same in the current stable v8.x releases.
Version‑Specific Behavior

v7.x & v8.x: strict peer resolution; install fails on conflict.
Newer releases (v9.x and beyond) have not yet introduced deterministic hoisting or automatic overrides, so the same policy applies.

How pnpm Reports the Conflict
The error message lists the two packages that cannot coexist, the required version ranges, and the installed versions that caused the clash. Example:
ERESOLVE unable to resolve dependency tree
│
├─ conflicting peer: react@^17.0.0 required by @mui/material@5.12.0
└─ installed: react@18.2.0

Detecting Conflicts Programmatically

Run pnpm install --reporter ndjson to get structured JSON output.
Parse the stream for objects where code equals ERESOLVE.
Use the details field to determine which packages are involved and why.

When to Relax the Policy
If you intentionally want to ignore a conflict (e.g., for a quick prototype), you can:

Use the command‑line flag --legacy-peer-deps—pnpm will continue with warnings.
Set peerDependencies=auto in .npmrc to achieve the same effect across installs.

Recommended Steps for a Reproducible CI Pipeline

Pin the pnpm version in .nvmrc or package.json to a specific v8.x release.
Run pnpm install --reporter ndjson and capture the output in a log file.
Parse the log for ERESOLVE entries; if any exist, fail the CI job and surface the conflict details.
Optionally, run pnpm install --legacy-peer-deps only in a “quick‑build” branch to test whether the conflict is benign.

What to Do If the Conflict Persists
Check the peerDependencies of the conflicting packages and consider:

Upgrading or downgrading one of the packages to a compatible version.
Using overrides in pnpm-workspace.yaml to force a single version of the peer.
Removing an unnecessary dependency that brought in the peer constraint.

Missing Diagnostic Detail
To tailor the recommendation to your setup, could you share the exact pnpm version you are using (e.g., pnpm@8.5.0)?

ERESOLVE unable to resolve dependency tree: peer dependency conflict reporting

ERESOLVE unable to resolve dependency tree

1 answer

What pnpm Does When a Peer Conflict Happens

Version‑Specific Behavior

How pnpm Reports the Conflict

Detecting Conflicts Programmatically

When to Relax the Policy

Recommended Steps for a Reproducible CI Pipeline

What to Do If the Conflict Persists

Missing Diagnostic Detail

Your perspective belongs here.

0 question comments