pnpm ERR_PNPM_PEER_DEP_ISSUES - Fix Strict Peer Failures in CI

pnpm validates peer dependencies strictly by default. When peers are missing or mismatched, it aborts with ERR_PNPM_PEER_DEP_ISSUES rather than merely warning - so CI fails where npm might only have grumbled.

What this error means

pnpm install fails with ERR_PNPM_PEER_DEP_ISSUES, listing unmet or conflicting peer dependencies. The same dependency set installs (with warnings) under npm, because pnpm enforces peers more strictly.

pnpm output

ERR_PNPM_PEER_DEP_ISSUES  Unmet peer dependencies

.
└─┬ some-plugin 3.0.0
  └── ✕ unmet peer react@"^18": found 17.0.2

hint: If you want to ignore deliberately, add the package to
"pnpm.peerDependencyRules.allowedVersions"

Common causes

A real peer mismatch in the tree

A package requires a peer (e.g. React 18) that conflicts with the version your project pins (React 17). pnpm refuses to proceed with the mismatch.

A missing peer that npm would have auto-installed

pnpm does not auto-install peers the way some npm versions do; an unprovided peer becomes a hard error under strict mode.

How to fix it

Resolve the peer version (preferred)

Align the conflicting versions so the peer requirement is genuinely satisfied.

Terminal

# upgrade/downgrade so the peer matches, then:
pnpm install

Declare a deliberate exception narrowly

If you have verified compatibility, allow the specific version via peerDependencyRules instead of disabling strictness globally.

package.json

// package.json
"pnpm": {
  "peerDependencyRules": {
    "allowedVersions": { "react": "17" }
  }
}

How to prevent it

Keep packages and their peers on compatible majors.
Use peerDependencyRules for verified, intentional exceptions only.
Commit the pnpm-lock.yaml so peer resolution is reproducible.