ERR_PNPM_PEER_DEP_ISSUES" unmet peer dependencies after an upgrade

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 ERRPNPMPEERDEPISSUES 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

"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 ERRPNPMPEERDEPISSUES.
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 ERRPNPMPEERDEPISSUES 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 ERRPNPMPEERDEPISSUES
• 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

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

Thread query: "ERRPNPMPEERDEPISSUES" unmet peer dependencies after an upgrade

TL;DR: