pnpm ERR_PNPM_PEER_DEP_ISSUES in CI - Fix Strict Peer Dependency Failures

By Kaveh Alemi·Latchkey

pnpm reports unmet peers as suggestions, but with strict-peer-dependencies enabled it raises ERR_PNPM_PEER_DEP_ISSUES and fails the install rather than warning.

What this error means

pnpm install aborts with ERR_PNPM_PEER_DEP_ISSUES, listing missing or mismatched peers. Without strict mode the same issues appear only as a non-fatal suggestion block.

ERR_PNPM_PEER_DEP_ISSUES  Unmet peer dependencies
.
 @acme/ui 4.2.0
   missing peer react@^18: found 17.0.2

Common causes

A required peer is missing or on the wrong version

A dependency expects a peer (a framework or library) that is absent or pinned to an incompatible major.

strict-peer-dependencies promotes warnings to errors

With the strict setting on, any unmet peer fails the install instead of producing a suggestion.

How to fix it

Satisfy the unmet peers

1. Read the listed peers and required ranges.
2. Add or upgrade each peer to a compatible version, then reinstall.

pnpm add react@^18

Pin specific peers via package.json overrides if intentional

1. Use pnpm.peerDependencyRules to ignore a known-safe mismatch deliberately.
2. Reserve this for cases you have verified at runtime.

How to prevent it

• Keep strict-peer-dependencies on to catch issues early, add required peers explicitly, and use peerDependencyRules only for mismatches you have verified are safe.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation