npm install stops before writing anything, and instead of a package list you get a tree dump:
npm error code ERESOLVE npm error ERESOLVE unable to resolve dependency tree npm error While resolving: my-app@1.0.0 npm error Found: react@18.3.1 npm error Could not resolve dependency: npm error peer react@^19.0.0 from chart-lib@2.4.0 The line that matters is always peer … from …: the project already decided one version, a dependency's peerDependencies excludes it, and npm refuses to guess.
Why it happens at all
Since npm 7, peer dependencies are installed automatically and a conflicting peer range is a hard error. npm 6 installed peers only with a warning, so this class of failure did not exist before. npm builds one tree per project, and each package name resolves to exactly one directory — node_modules/react cannot be two versions.
A four-line reproduction in an empty directory:
mkdir eresolve-demo && cd eresolve-demo npm init -y npm pkg set dependencies.react="^18.3.1" npm pkg set dependencies.chart-lib="^2.4.0" # this version peers on react@^19 npm install # npm error code ERESOLVE Read the tree before you pick a flag
| Line npm prints | What it tells you |
|---|---|
While resolving: | the package whose dependencies are being resolved |
Found: | the version already chosen for that name, and who asked for it |
Could not resolve dependency: | the package whose peer range excludes that version |
npm ls react # which versions exist, and who requires them npm explain chart-lib # why the package is in the tree at all npm view chart-lib peerDependencies --json npm view chart-lib versions --json | tail -20 That last pair is the cheapest fix path: if a newer patch widened the peer range, upgrading beats every override you could write.
Four strategies, in the order worth trying
| Strategy | What it changes | Lockfile | Take it when |
|---|---|---|---|
| Upgrade the dependent | its peerDependencies range | clean | a release accepts your version — always first |
overrides | resolution for the whole tree | clean and reproducible | a transitive package lags behind |
--legacy-peer-deps | skips peer installation (npm 6 behaviour) | records the skipped peers | plugin ecosystem, migration in progress |
--force | installs anyway, may duplicate | can hold duplicates and broken peers | never in CI; a local unblock only |
npm install --strict-peer-deps is the inverse: it refuses to auto-pick when ranges conflict, which is what you want in CI when failing is better than drifting.
overrides that actually apply
{ "dependencies": { "react": "^19.1.0", "chart-lib": "^2.4.0" }, "overrides": { "chart-lib": { "react": "$react" } } } -
$reactmeans "the version the root manifest resolves", so the pin follows your own dependency instead of being copied in and going stale. - The field applies to the entire tree, including packages you never import directly.
- In a workspace,
overridesinside a package's ownpackage.jsonis ignored. Only the root counts:
npm pkg set 'overrides.react=$react' -w . # writes the root manifest npm install --workspaces If two workspaces genuinely need different React majors, they need separate lockfiles and separate installs. No override makes one node_modules hold two Reacts safely.
When the tree is already installed
npm reuses an existing node_modules, so an overrides edit can silently fail to reach a nested copy:
rm -rf node_modules package-lock.json && npm install A merge that combined two lockfiles can raise ERESOLVE on a manifest that is perfectly fine. Inspect before deleting anything:
npm ls --all 2>&1 | grep -i "invalid\|peer\|ERR" npm install --package-lock-only # does the manifest resolve at all? --package-lock-only is the safe first move after a merge: it answers the question without destroying a working node_modules you may still need. npm ci is the only command that promises "exactly this lockfile or nothing".
The traps in the containment strategies
-
--legacy-peer-depstyped once in one terminal is recorded nowhere. The next person'snpm cifails the same way — put it in.npmrcor remove the need for it. -
--forcesilences the error by installing conflicting copies. The failure then reappears at runtime as two React instances, a dead context, or an invalid hook call. -
peerDependenciesMeta: { optional: true }means npm 7+ does not fail when the peer is absent, so anERESOLVEnaming an optional peer usually points at a second, real conflict above it in the tree. - A
yarn.lockbeside apackage-lock.jsonproduces two disagreeing resolutions. Commit one, delete the other. - Node 20 ships npm 10 and Node 18 ships npm 9; the error text and resolution details differ. Pin the Node version in CI and in
.nvmrc. - A global install has no
overridesfield to edit. Usenpx some-cli@latestornpm exec --package=some-cli@latest -- some-cli --helpfor one-off tools instead.
Version cheat sheet
| npm | Peer dependencies | Conflict result |
|---|---|---|
| 6 | warnings only, not installed | npm WARN, working tree |
| 7 | installed automatically | ERESOLVE (introduced here) |
| 8 | installed automatically, overrides supported | ERESOLVE, fixed by overrides |
| 8.3+ | $package references inside overrides | pin to the root's own version |
| 9 / 10 / 11 | same rules, npm error prefixes | richer Could not resolve text |
A package-lock.json generated by npm 6 will not reproduce on npm 10, because npm 6 never recorded the peers it skipped.
The longer version, with the workspace and lockfile cases in full, is on my site: npm ERESOLVE unable to resolve dependency tree: 4 fixes.

