skip to content

With npm 7 or later, an app moves its UI framework to version 5 and `npm install` stops with `ERESOLVE` because a chart library peers on `^4`; what happened, and what do `--legacy-peer-deps` and `--force` change?

level: seniorimportance: should knowfreq 18%

answer

  1. one shared copy cannot satisfy both
  2. While resolving, Found, Could not resolve
  3. deep conflicts only warn by default
  4. legacy-peer-deps: peers ignored tree-wide
  5. widen the library's peer range

basics

~10 s

The app's viewlib@5 and the library's peer range ^4 must share one copy, which is impossible, so npm stops with ERESOLVE. --legacy-peer-deps ignores every peer; --force accepts the conflict. Neither makes the pair compatible.

solid answer

~50 s

Since npm 7 peers are part of the tree npm must build: `@fleetline/charts` promises to run against the app's single `viewlib`, and the app now asks for 5 while the library allows only `^4`, so no placement satisfies both and npm stops with `ERESOLVE`, printing what it was resolving, what it found, the dependency it could not resolve and the conflicting peer. `--legacy-peer-deps` makes npm ignore `peerDependencies` everywhere while building the tree, as npm 3 to 6 did, so the install passes but no peer contract is checked for any package. `--force` keeps peer handling but accepts the conflicting peer in the root project. Neither makes the library work with version 5. The real fix is a library release whose peer range includes `^5` after testing against it, or holding the app on 4 until then; `--omit=peer` does not help, because npm still plans the tree for peers.

go deeper

for a junior

Recall that ERESOLVE means npm cannot build a tree that satisfies every peer range, and that the flags it suggests accept a possibly broken result.

for a middle

Read the While resolving, Found and Could not resolve lines to name the library and the range that block the upgrade.

for a senior

Distinguish --legacy-peer-deps, --force, --omit=peer and strict-peer-deps, and push for a widened peer range or a held upgrade over a committed flag.

for a principal

Set a team policy for framework major upgrades: who checks peer ranges across libraries, and when a temporary peer flag is acceptable.

## Why the install stops A **peer dependency** says a package must run against the host copy the consuming project uses. Since npm 7, npm installs peers by default, which means it must also *resolve* them: the tree it builds has to give every package a host that satisfies its declared range. In the dispatch dashboard, `package.json` now asks for `viewlib@^5.0.0`, while `@fleetline/charts` declares `"viewlib": "^4.0.0"` in `peerDependencies`. Because `@fleetline/charts` sits at the top of the app's tree, its peer has to be the copy at the top too, which is the app's own `viewlib`. One copy of `viewlib` cannot be both 5.x and 4.x, so npm refuses rather than guess. The error code is **`ERESOLVE`**. npm's explanation follows a fixed shape, and reading it top to bottom finds the culprit: 1. **While resolving:** the package being placed when the conflict surfaced. 2. **Found:** the version already in the tree, with the chain of packages that require it. 3. **Could not resolve dependency:** the edge that cannot be met, here the library's peer on `viewlib@^4`. 4. **Conflicting peer dependency:** the peer version that the edge would need. npm writes the full report to `eresolve-report.txt` in its cache folder and ends with a sentence telling you to fix the upstream conflict or retry with `--force` or `--legacy-peer-deps` "to accept an incorrect (and potentially broken) dependency resolution". ## Not every peer conflict is fatal The `strict-peer-deps` config defaults to `false`. With that default, a conflicting peer range **deep in the graph** is resolved from the nearest non-peer dependency specification, even if a package ends up with a peer outside its declared range, and npm prints a warning naming the packages involved. A conflict that involves what the root project itself asks for, as in this upgrade, is the kind that typically stops the install. Setting `strict-peer-deps=true` turns those deep warnings into failures too, for teams that want every peer contract enforced. ## What each escape hatch actually turns off | Option | What npm does | Cost | |---|---|---| | `--legacy-peer-deps` | ignores `peerDependencies` entirely while building the tree, as in npm 3 to 6 | no peer contract is checked or installed anywhere in the tree, not just this one | | `--force` | among other protections, allows conflicting peers to be installed in the root project | the conflict is accepted, not fixed; `--force` also relaxes engine checks and other safeguards | | `--omit=peer` | still designs the tree for peers, just does not unpack them | does not resolve the conflict at all | | `strict-peer-deps=true` | fails on deep peer conflicts too | stricter, never more permissive | npm's own description of `legacy-peer-deps` says its use "is not recommended", because it stops enforcing the peer contract that other packages may rely on. Once it is committed to a project `.npmrc`, every later `npm install` and `npm ci` in that project runs with peers ignored. ## Fixing the conflict instead of hiding it The flags change what npm checks; they do not change whether `@fleetline/charts` works on `viewlib` 5. The options that keep the contract: - **Widen the peer range in the library**, after testing against the new major: `"viewlib": "^4.0.0 || ^5.0.0"`, released as a new library version. The app then upgrades both together. - **Hold the app on `viewlib` 4** until such a release exists, if the library is not yours to change. - **Look for an existing library version** whose peer range already includes 5; `npm view @fleetline/charts@<version> peerDependencies` shows a version's peer ranges before you install it. - If you must ship before the library catches up, use a flag **as a recorded, temporary decision**: note why, test the affected screens, and remove it when the library releases. ## Habits that prevent the next one - Library authors write peer ranges as broad as they genuinely support and run their tests against every major in that range. - App teams upgrade a framework major in a branch, read the `ERESOLVE` output to list every library that peers on the old major, and plan those upgrades together. - Nobody adds `legacy-peer-deps=true` to a shared `.npmrc` to make a red build green without a ticket to remove it. In an interview, the strongest answer names the mechanism (one shared copy, two incompatible ranges), reads the error rather than reaching for a flag, and can say exactly how `--legacy-peer-deps` differs from `--force` and `--omit=peer`.

  • A teammate committed `legacy-peer-deps=true` to the project `.npmrc` months ago. What risk does that carry today?
    Every install in the project ignores `peerDependencies`, so npm no longer installs missing peers or reports any peer mismatch, for every package, not just the original one. A library could silently run against an unsupported framework version. Remove the setting, run `npm install`, and fix each `ERESOLVE` it surfaces properly.
  • Why does a peer conflict between two transitive packages often produce only a warning?
    With the default `strict-peer-deps=false`, npm resolves conflicting peers deep in the graph from the nearest non-peer dependency spec and prints a warning naming the packages involved. Setting `strict-peer-deps=true` makes such warnings fail the install, which suits teams that want every peer contract enforced.

  • --legacy-peer-deps relaxes only the one conflicting peer
  • --omit=peer resolves an ERESOLVE conflict
  • --force makes the library compatible with the new major
  • ERESOLVE means the registry is unreachable
  • every peer conflict anywhere in the tree stops the install by default