pnpm ERR_PNPM_PEER_DEP_ISSUES - Fix Unmet Peer Dependencies in CI

pnpm checks peer dependencies strictly and, with strict-peer-dependencies on, fails the install when peers are unmet - surfacing conflicts npm/yarn might only warn about.

What this error means

pnpm install fails with ERR_PNPM_PEER_DEP_ISSUES, listing packages whose peer dependencies are missing or version-mismatched. The real fix is to satisfy the peers, not to blanket-disable the check.

pnpm output

ERR_PNPM_PEER_DEP_ISSUES  Unmet peer dependencies

.
└─┬ @some/ui 3.1.0
  └── ✕ unmet peer react@^18.0.0: found 17.0.2

Common causes

A peer dependency is unmet or mismatched

A package needs a peer (e.g. React 18) that is absent or at an incompatible version in your tree.

strict-peer-dependencies turns warnings into failures

pnpm fails the install on unmet peers under strict mode, where other managers might only warn.

How to fix it

Satisfy the peer (preferred)

Install or align the required peer versions.

Terminal

pnpm add react@^18 react-dom@^18
# or pin an override in package.json:
# "pnpm": { "overrides": { "react": "^18" } }

Use peerDependencyRules deliberately

For a known-safe mismatch, allow it via pnpm.peerDependencyRules rather than disabling all strictness.
Avoid blanket strict-peer-dependencies=false; it hides real incompatibilities.
Regenerate the lockfile after resolving peers.

How to prevent it

Keep packages and their peers on compatible majors.
Use peerDependencyRules for specific, vetted exceptions.
Commit the lockfile and install consistently.