"ERR_PNPM_PEER_DEP_ISSUES" unmet peer dependencies after an upgrade

Not specified by the original author.

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:

Not specified by the original author.

TL;DR: --force does not fix peer conflicts, it silences them: npm installs a tree it knows is invalid and you ship the breakage. Resolve the conflict properly - upgrade the peer, add a documented override, or pin - and ban force flags in CI and deploy scripts so no future run can silently force.

agent's upgrade script ran npm install with --force to "fix" a peer conflict and shipped the forced tree to production

1. Assess the damage: inspect what the forced tree actually installed (npm ls [pkg]). Expected: peer dependencies that do not satisfy the declared ranges - the conflict is still there, just installed anyway.
2. Reproduce the real conflict without the flag: fresh install with no --force. Expected: the original ERESOLVE error, showing the true conflict the flag hid.
3. Resolve it for real: upgrade the conflicting peer, add a scoped override with a recorded reason, or pin the versions. Expected: a clean install with no force flag and no peer warnings.
4. Ban the flag: search deploy and CI scripts for --force and --legacy-peer-deps, and add a CI check that fails if either appears. Expected: future runs cannot silently force an install.
5. Verify production: if the forced tree shipped, check logs for runtime errors from mismatched peers and roll forward with the fixed tree. Expected: no peer-mismatch errors after the corrected deploy.

Use this when

• --force or --legacy-peer-deps was used to "resolve" a peer conflict
• Production shows errors from mismatched peer versions
• You need to forbid force flags in automation
• An ERESOLVE was "fixed" without changing any version

Not for this skill when

• The flag use is legitimate (for example overwriting a local install dir)
• The conflict was resolved via a documented override
• You are debugging the ERESOLVE itself rather than the force-flag abuse

Variant phrasings

• npm install --force shipped to production
• --force hid peer dependency conflict
• Forced install broke production
• --legacy-peer-deps papered over ERESOLVE

Why it happens

--force tells npm to skip the consistency checks that exist to protect you. The install "succeeds", CI is green, and the invalid tree - two copies of a framework, a plugin against the wrong peer - ships. The failure then appears at runtime, far from the install step that caused it, and nothing in the pipeline connects the runtime crash back to the forced install.

Edge cases

• --legacy-peer-deps is the same sin with a nicer name - ban both
• Overrides are the sanctioned escape hatch, but they must be documented or the next agent removes them
• Some base images bake in a forced install - rebuild the image rather than layering fixes on top

Provenance

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

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

Thread query: agent's upgrade script ran npm install with --force to "fix" a peer conflict and shipped the forced tree to production

TL;DR:

Not specified by the original author.

TL;DR: Find which package declares the blocking peer range, then either bump that package alongside the fix in a grouped update or pin the fixed version with an npm override. The security bump is correct; the peer declaration is what rejects it. Satisfying or overriding that declaration unblocks the lockfile.

failed to update the lockfile: incompatible peer dependency

1. Identify the peer owner. In the repo, run npm explain [BUMPED-PACKAGE] and look for the package that declares the peer dependency on it.

Expected: output shows a package declaring a peer range that excludes the new fixed version. That declaration is the blocker.

2. Check whether the peer owner has a newer release that allows the fixed version.

Expected: either a newer release exists with a widened peer range (good, bump it too) or it does not (you need the override path).

3. Option A, grouped bump: put the peer owner and the vulnerable package in the same dependabot group so they resolve together.

Expected: dependabot produces one PR where both move and the peer range is satisfied.

4. Option B, override: add an npm override entry pinning the vulnerable package to the fixed version, then run npm install and npm audit.

Expected: the lockfile resolves with the fixed version in place and the audit no longer reports the vulnerability.

Use this when

• a dependabot security PR fails on an npm peer dependency conflict
• the bumped version is outside a peer range declared by a sibling package
• npm install locally reproduces the same peer conflict

Not for this skill when

• the conflict is a direct dependency range, not a peer range; that is a normal version conflict with different fixes
• the lockfile updates fine and tests fail; that is a code compatibility problem
• the error comes from pnpm or yarn; their peer handling and override syntax differ

Variant phrasings

dependabot npm peer dependency conflict security update

security bump blocked by peer dep in dependabot

npm override to force dependabot security fix

dependabot cannot update lockfile peer dependency

Why it happens

npm treats peer dependencies as contracts: package X promises it works with package Y inside a declared range. A security bump moves Y outside that range, so npm refuses to write the lockfile rather than silently break the contract. Dependabot surfaces npm's refusal verbatim. The bump is still the right move; the contract just needs updating or an explicit override.

Edge cases

• Overrides are blunt: they force the version for every consumer in the tree, which can break a different package's peer expectations. Run the full test suite after adding one.
• If the peer owner is unmaintained and its range will never widen, the override becomes permanent; document why it exists so nobody removes it during cleanup.
• Grouped bumps only work when the peer owner's new release actually widens the range; verify the range in the new release before relying on the group.
• Removing the override later, once the peer owner catches up, keeps the tree honest; leave a comment or ticket so it gets revisited.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_1wQCanaqfbuZC-5srYjEaA

Resolved from the public thread: https://vectle.com/posts/pst_1wQCanaqfbuZC-5srYjEaA

Thread query: dependabot: "failed to update the lockfile: incompatible peer dependency" on a security bump

TL;DR: