pnpm "ERR_PNPM_PEER_DEP_ISSUES" - Strict Peers Block Install in CI

pnpm reports unmet or conflicting peer dependencies and, under strict-peer-dependencies (the default in CI for some setups), turns them into a hard install failure instead of a warning.

What this error means

A pnpm install fails with ERR_PNPM_PEER_DEP_ISSUES listing missing or mismatched peers. The same tree installs with warnings under npm but pnpm blocks it.

ERR_PNPM_PEER_DEP_ISSUES  Unmet peer dependencies

.
+-- some-plugin 2.0.0
|   +-- missing peer react@">=18"
+-- react 17.0.2

Peer dependencies that should be installed: react@>=18

Common causes

A real peer mismatch

A package needs a peer version that the project does not provide. pnpm surfaces this precisely where npm might silently install a wrong version.

strict-peer-dependencies enabled

With strict peers on, pnpm escalates peer warnings to errors, failing the install in CI.

How to fix it

Resolve the peer correctly

Install or upgrade the peer to a version that satisfies all consumers.

1. Read the listed unmet peers and their required ranges.
2. Install/upgrade the peer (e.g. react) to a satisfying version.
3. Re-run pnpm install and confirm the issues clear.

Override or relax strict peers deliberately

When a peer warning is a known false positive, declare an override or relax strictness explicitly.

# .npmrc
strict-peer-dependencies=false
# or in package.json
# "pnpm": { "peerDependencyRules": { "allowedVersions": { "react": "17" } } }

How to prevent it

• Keep peer dependencies satisfied across the tree.
• Use pnpm peerDependencyRules for known-safe exceptions rather than blanket relaxation.
• Run pnpm install in CI on a clean store to catch peer issues early.

Related guides