Read the conflict message, find which package wants which version of the shared host, and either upgrade the pair together or hold the update until the plugin supports the new host. Forcing the install past the error hides a real incompatibility.
What a peer dependency is
The npm documentation describes peer dependencies as a way to express compatibility with a host package without requiring it directly. They are typical for plugins. A plugin says it works with host versions in some range, and you provide the host.
Two details from the documentation matter for update pull requests. Since npm v7, peer dependencies are installed by default, where versions 3 through 6 did not install them automatically. And peer dependencies can be marked optional through peerDependenciesMeta, in which case npm will not automatically install them.
The same page suggests keeping peer ranges broad. If the host follows semver, only a major version change should break the plugin, so ranges such as ^1.0 or 1.x make sense.
Why a bot update triggers it
A bot upgrades one package at a time unless you group them. If it bumps the host to a new major while an installed plugin only accepts the old major, installing fails with a conflict. The bot did nothing wrong. It did not know your plugin has not caught up.
Steps to resolve
- Read the error. It names the package that declares the peer range and the version it found.
- Check the plugin's latest release. Does a newer version accept the new host range?
- If yes, upgrade both in one change. A name pattern group in your bot helps here, so the pair arrives together.
- If no, close the pull request and tell the bot to ignore that major for the host until the plugin catches up. Add a note with a revisit date.
- If the plugin is abandoned, plan a replacement. A dependency that blocks upgrades indefinitely is a maintenance risk by itself.
- Avoid overrides and force flags as a first move. The overrides field replaces packages across the tree and only takes effect from the root package.json. It is a tool for a known safe case, not a way to silence errors.
Decision table
| Situation | Action |
|---|---|
| Plugin has a compatible release | Upgrade host and plugin together |
| Plugin lags a major behind | Ignore the host major, set a review date |
| Plugin abandoned | Replace it |
| Optional peer, unused by you | Check that it is marked optional |
Record the decision
Whichever path you take, write down why. The next person who sees the bot propose the same update will ask the same question.
Quick check
Is it safe to use legacy peer dependency flags?
They suppress the check rather than fix it. Use them only as a short, documented stopgap while you plan the real upgrade.
Who should fix a peer range that is too narrow?
The plugin maintainer. Their package declares the range. You can open an issue, and the npm documentation suggests keeping ranges broad.
Safeguard scans manifests and lockfiles into an SBOM, uses reachability analysis to show which flagged dependencies your code actually calls, and can open fix pull requests (off by default, every category on Manual). You can try a free scan on a public repository.
Sources
Last reviewed: 19 October 2026.
