npm ERR! ERESOLVE: Fix Dependency Conflicts Fast

You run npm install after adding one harmless package, and instead of a progress bar you get a wall of red: npm ERR! ERESOLVE could not resolve, While resolving X, Found Y, Could not resolve dependency. Nothing you wrote is wrong, yet the install refuses to proceed. If you have shipped JavaScript since npm 7, you have stared at this report — and if you have not, your first encounter is only one dependency away.

The frustration is understandable, but the error is doing you a favor. Before npm 7, conflicting peer demands were waved through with a warning, and apps shipped with two copies of React or a date picker wired to the wrong version. Those installs succeeded and then broke at runtime in ways nobody could trace. ERESOLVE fails loudly at install time so you fix the wiring before your users find it.

This guide teaches you to read the report like a work order: who demands what, which copies collide, and which fix fits. You will learn the npm ls plus dedupe workflow for mapping conflicts, the overrides field for pinning transitive copies, and the honest risks of --legacy-peer-deps. You will also learn the lockfile discipline that keeps conflicts fixed — including why deleting node_modules is the last resort, not the first step.

Why npm v7 Turned Peer Clashes Into Hard Errors

Peer dependencies are a package's way of saying I need to share one copy of something with your app. A plugin does not bundle its own React — it declares react as a peer and expects your project to provide exactly one. That design prevents duplicate stateful libraries, which break hooks, contexts, and singletons. Through npm 6, the installer treated peer clashes as advisory: it printed a warning, installed whatever fit best, and moved on. Most teams never read those warnings, so applications routinely shipped with doubled libraries and mystery runtime bugs.

npm 7 replaced the installer with arborist, a resolver that builds the entire dependency tree as one constraint problem before downloading anything. Every peer range becomes a hard requirement, and when no single version satisfies all of them, the install stops with ERESOLVE instead of guessing. This strictness felt like a regression to teams upgrading npm — installs that worked for years suddenly failed — but it converted silent runtime corruption into loud install-time failures. A red build you can read beats a green build that crashes in production.

The practical consequence is that peer ranges now deserve the same respect as your own dependencies. Before adding any package, inspect its peer demands with npm view and compare them against your installed majors. If a plugin wants React 17 and you run 18, you have three honest options: upgrade the plugin, downgrade your app (rarely wise), or pin the tree with overrides after verifying compatibility. What you cannot do anymore is ignore the mismatch and hope — arborist removed hope from the process, and your installs are better for it.

# Which resolver are you even running? ERESOLVE strictness started with npm 7.
npm --version
node --version

# See what a suspect package demands before you install it
npm view eslint-config-react-app peerDependencies

# Dry-run an install to preview conflicts without touching node_modules
npm install --dry-run 2>&1 | head -40

Reading the ERESOLVE Report Line by Line

An ERESOLVE report looks intimidating, but it contains exactly three facts plus an advertisement. Fact one sits on the While resolving line: it names the package whose demand could not be satisfied, often your root project or a plugin you just added. Fact two sits on the Found lines: they list the versions already placed in the tree, with their locations — top level versus nested under some parent. Fact three sits on the Could not resolve line: it states the required range that nothing in the tree meets. Everything after that, including the suggestion to retry with --legacy-peer-deps, is npm's generic escape hatch, not a recommendation.

Read a React 17 versus 18 clash through this lens and it becomes a work order. While resolving: your-app names your project as the requester. Found: react@18.2.0 at the top level shows what you run. Found: react@17.0.2 nested under the analytics package shows the intruder. Could not resolve: react@17.x from the analytics plugin states a demand your tree cannot meet without demoting your whole app. The fix space is now obvious and small: make the plugin accept 18 (upgrade it), force one copy with overrides, or remove the plugin. None of that requires touching node_modules.

Build one reading habit and most reports surrender in minutes: scan upward from the bottom until you find the first While resolving line, then read downward through its Found and Could not resolve lines as a group. Reports can chain several groups when multiple clashes exist — resolve them one group at a time, starting with the shared libraries (react, typescript, eslint) whose duplicates cause the worst runtime damage.

npm ls and npm dedupe: Mapping the Conflict

Once the report names the clash, npm ls draws you a map of it. Running npm ls with the conflicted package name prints every installed copy and, critically, the chain of parents above each one — so you can see that react@18.2.0 sits at the top level while react@17.0.2 hides two levels deep under the analytics plugin. That parent chain is the whole game: it tells you whether the fix belongs in your direct dependencies or in an overrides entry aimed at a transitive one. Run npm ls before every fix attempt and after, so you have a before-and-after picture instead of vibes.

npm dedupe plays the supporting role. After hoisting analysis, npm can often collapse duplicate minor versions into one shared copy when their ranges overlap — three nested copies of a utility at 4.17.20 and 4.17.21 become one. Run it, then re-run npm ls to see what survived. Whatever remains after dedupe represents genuinely incompatible demands (different majors, disjoint ranges) that no hoisting trick can merge. That boundary matters because it tells you when to stop tidying and start deciding: upgrade a package, pin with overrides, or replace the offender.

Two companion commands round out the mapping kit. npm view with the peerDependencies field shows what any published version demands without installing it — perfect for checking whether a newer plugin release already supports your major. npm outdated flags how far your pins lag, which hints whether an upgrade path even exists. Together these turn dependency archaeology from guesswork into a fifteen-minute routine: map with ls, tidy with dedupe, research with view, and only then edit package.json.

# Map every copy and the parents pulling it in
npm ls react

# See exactly what a published version demands (no install needed)
npm view some-analytics-plugin peerDependencies
npm view some-analytics-plugin versions --json

# Collapse duplicates whose ranges overlap, then re-map
npm dedupe
npm ls react

# How far behind are the candidates for upgrade?
npm outdated react some-analytics-plugin

The overrides Field: Pinning Your Way Out

The overrides field is package.json's way of settling transitive disputes by fiat: it forces one version of a package across your entire tree, no matter what nested dependencies request. When an analytics plugin demands react@17.x and your app runs 18.2.0, an override pinning react to 18.2.0 tells arborist to place that copy everywhere and skip the unsatisfiable demand. One edit, one npm install to rebuild the lockfile, and the resolver that failed for hours goes green. The snippet below shows the shape — an overrides block keyed by package name with the exact version you have already tested.

Overrides demand respect because they override compatibility claims you did not write. Pinning React 18 under a plugin built for 17 can work flawlessly or break subtly, so verify like you mean it: run the full test suite, exercise the plugin's UI paths in staging, and confirm with npm ls that exactly one copy remains. Prefer upgrading the requesting package first — a plugin release whose peer range already includes your major needs no forcing at all. Reach for overrides when the upgrade does not exist yet, the maintainer is slow, or the old peer range is needlessly narrow for code that works fine.

Keep overrides visible and temporary where possible. Comment each entry with why it exists and which upstream release would let you remove it, and re-check on every dependency upgrade pass. An overrides block with no comments becomes permanent furniture that nobody dares touch — the same trap as a committed --legacy-peer-deps flag, just better dressed. Review them quarterly: the best override is the one you delete because the ecosystem caught up.

{
  "name": "your-app",
  "private": true,
  "dependencies": {
    "react": "18.2.0",
    "some-analytics-plugin": "3.4.0"
  },
  "overrides": {
    "react": "18.2.0"
  }
}

--legacy-peer-deps: What It Hides and When It Is Safe

The --legacy-peer-deps flag tells npm to resolve peers the way npm 6 did: install through the clash, print warnings nobody reads, and hope the tree works. As a local, temporary unblock it has legitimate uses — you need a build running this afternoon while the real fix waits on a plugin release. The danger starts when temporary becomes permanent: committed into .npmrc, baked into Dockerfiles, pasted into runbooks. At that point every future peer clash across every dependency installs silently, and your team loses the exact protection arborist was built to provide.

What it hides is concrete and nasty. Duplicate copies of stateful libraries — two Reacts, two emotion instances, two router contexts — where hooks fire against the wrong copy and contexts read as empty. A plugin wired to an incompatible major that throws only on the one code path your tests skip. None of this appears at install time because you disabled the check that would have named it. The Tuesday incident is the textbook case: the flag produced a green laptop install with react 17 nested under the plugin, and staging crashed with invalid hook calls that took longer to diagnose than the original conflict.

If you must use it, fence it in. Pass it on the command line for one install, never commit it, and open the tracking ticket in the same hour with the overrides-or-upgrade plan attached. Grep the repo for it in CI and fail builds that smuggle it into .npmrc without an expiry comment. And remember its honest alternative: --strict-peer-deps, which turns even warnings into errors so new clashes surface in pull requests instead of release branches.

# Temporary local unblock ONLY — do not commit this
npm install --legacy-peer-deps

# Prove what the flag hid: look for duplicated singletons
npm ls react

# Find every place the flag might be smuggled in
cat .npmrc 2>/dev/null
grep -rn "legacy-peer-deps" .npmrc Dockerfile* .github/ 2>/dev/null

# Stricter alternative for CI: fail on warnings too
npm install --strict-peer-deps

Lockfile Discipline: Why Deleting node_modules Comes Last

The lockfile is the only record of the tree that actually worked, so treat it as a first-class artifact. package-lock.json pins every transitive version, which means npm ci on any machine rebuilds the identical tree that passed your tests. That determinism is exactly what ERESOLVE fixes need: after overrides or upgrades resolve the clash, npm install writes the settlement into the lockfile, you commit it, and every teammate plus CI installs the settled tree instead of re-litigating the conflict. A fix that is not in the lockfile is a rumor, not a resolution.

This is also why deleting node_modules fixes nothing. The conflict lives in version requirements — ranges in package.json and pins in the lockfile — while node_modules holds only downloaded files. Wiping the folder and reinstalling replays the same resolver against the same requirements and fails identically, ten minutes later. Reserve deletion for its real uses: corrupted downloads, phantom binaries after an interrupted install, or native modules built against the wrong Node version. Those are file problems with file solutions; ERESOLVE is a requirements problem with a requirements solution.

Build the discipline into your workflow and conflicts stop recurring. Commit the lockfile for every application (libraries may differ, apps must not). Prove fixes with rm -rf node_modules plus npm ci on a clean checkout before merging. Run npm ci — never bare npm install — in CI so a stale lockfile fails loudly instead of being silently rewritten. The teams that follow this routine spend dependency-upgrade days reviewing lockfile diffs calmly; everyone else spends release days re-running installs hopefully.

# Rebuild the lockfile after editing package.json (overrides, ranges, upgrades)
npm install

# Review what the resolver actually settled before committing
git diff --stat package-lock.json

# Prove the settlement on a clean tree — this is what CI must run
rm -rf node_modules
npm ci

# Final assertion: exactly one copy of the conflicted singleton
npm ls react