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" } } } 
  • $react means "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, overrides inside a package's own package.json is 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-deps typed once in one terminal is recorded nowhere. The next person's npm ci fails the same way — put it in .npmrc or remove the need for it.
  • --force silences 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 an ERESOLVE naming an optional peer usually points at a second, real conflict above it in the tree.
  • A yarn.lock beside a package-lock.json produces 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 overrides field to edit. Use npx some-cli@latest or npm exec --package=some-cli@latest -- some-cli --help for 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.