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.

```text
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