pnpm "ERR_PNPM_PEER_DEP_ISSUES" (strict-peer-dependencies) in CI

pnpm enforces strict-peer-dependencies by default. When an installed package declares a peer that is absent or a different major version, pnpm treats it as an error and stops the install.

What this error means

pnpm install fails with "ERR_PNPM_PEER_DEP_ISSUES Unmet peer dependencies" and a tree listing each package and the peer version it wanted versus what is present.

pnpm

ERR_PNPM_PEER_DEP_ISSUES  Unmet peer dependencies

.
+-- react-dom 18.2.0
|   +-- missing peer react@"^18.2.0"
+-- @testing-library/react 14.0.0
    +-- unmet peer react@"^18.0.0": found 17.0.2

Common causes

A required peer dependency is not installed

A package expects you to provide a peer (like react) as a direct dependency, and it is missing from package.json.

An installed peer is the wrong major version

A package needs react@^18 but the resolved tree has react@17, so the peer constraint is unsatisfied.

How to fix it

Add or align the peer dependency

Read the tree to see which peer is missing or mismatched.
Add the peer as a direct dependency at a compatible version.
Re-run pnpm install and commit the updated lockfile.

Terminal

pnpm add react@^18.2.0 react-dom@^18.2.0

Override or relax strictness deliberately

When a peer warning is a known false positive, encode a specific peerDependencyRules override rather than disabling all checks.

package.json

{
  "pnpm": {
    "peerDependencyRules": {
      "allowedVersions": { "react": "17" }
    }
  }
}

How to prevent it

Declare peer dependencies your app relies on as direct dependencies.
Keep frameworks and their ecosystem packages on aligned majors.
Prefer scoped peerDependencyRules over turning off strict-peer-dependencies.