# TL;DR

Install the missing peers explicitly or align the parent packages so their peer ranges agree - pnpm is strict about peers where npm is lenient. Read the ERR_PNPM_PEER_DEP_ISSUES output to see exactly which package wants which peer version, then `pnpm add` the peer at a satisfying version. The upgrade moved a package past what its dependents' peer ranges allow.

## Error

```text
"ERR_PNPM_PEER_DEP_ISSUES" unmet peer dependencies after an upgrade
```

## Steps

1. Read the full error. pnpm lists each unmet peer: which package declares it and which versions would satisfy it. Expected: a clear list like "package-a wants peer-b@^2 but none is installed."
2. Find the upgrade that broke it. Check what changed recently - usually one bumped package now requires a peer version nothing provides. Expected: you identify the single upgrade at the root of the mismatch.
3. Install the missing peer. Run `pnpm add [peer]@[version]` with a version satisfying the declared range. Expected: the peer appears in package.json and the lockfile updates.
4. Re-run the install. Run `pnpm install`. Expected: exit code 0 with no ERR_PNPM_PEER_DEP_ISSUES.
5. Decide on a standing policy. Either keep peers explicit in package.json, or enable pnpm's auto-install-peers setting so future installs resolve them automatically - but know that auto-install can mask real conflicts. Expected: a deliberate choice recorded in the repo config, not a surprise next time.

## Use this when

- pnpm install fails with ERR_PNPM_PEER_DEP_ISSUES after an upgrade
- A package's peer requirements changed in a new version
- Migrating from npm to pnpm surfaces peer problems npm silently tolerated
- An agent bumped a package without checking its peer declarations

## Not for this skill when

- The error is about peer conflicts rather than missing peers (pnpm has a separate strict-peer-dependencies error) - align versions instead
- You are on npm or yarn - their peer handling differs
- The peer is genuinely optional for your usage - consider whether you need it at all

## Variant phrasings

- pnpm unmet peer dependencies after upgrade
- pnpm install fails on peer dep issues
- how to fix ERR_PNPM_PEER_DEP_ISSUES
- pnpm strict peer dependencies breaking after bump

## Why it happens

pnpm refuses to install when peer dependencies are unmet, while npm historically auto-installed or warned. An upgrade can change a package's peer range (e.g. now requiring react@^19 instead of ^18) while nothing in your tree provides it. npm users never notice because npm papers over it; pnpm stops the install and tells you.

## Edge cases

- Auto-install-peers fixes the symptom but can install a peer version that subtly breaks another package - prefer explicit peers for important ones like react.
- If two packages demand incompatible peer ranges, no single version satisfies both - you need pnpm overrides or you need to upgrade one of the parents.
- Check whether the "unmet" peer is actually used at runtime; dev-only peers for a build plugin you do not use can sometimes just be installed to satisfy the checker.
- After fixing, run the test suite - a newly installed peer at a different major than before can change behavior.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_zXVdrd24xaB15VJgZmZkzg