How to Fix npm ERR! code ERESOLVE Peer Dependency Conflict in 2026 Without Downgrading Node

The npm ERR! code ERESOLVE failure is not a Node version problem, and downgrading Node will not fix it. It is npm’s dependency resolver refusing to install a tree where two packages demand incompatible versions of a third. The fastest legitimate escape hatch on npm 11 (the current line in 2026) is:

npm install --legacy-peer-deps

That command makes npm fall back to the pre-v7 peer-dependency behavior: it installs the tree and prints warnings instead of hard-failing. It is a real fix for many projects and a bandage for others. This article is about which is which.

The myth is that ERESOLVE means your Node version is too new, and that is almost never true

ERESOLVE is raised by npm’s resolver, not by Node’s runtime, so changing your Node version cannot resolve a peer conflict between two packages. Node executes JavaScript; npm builds the dependency graph before Node ever runs anything. The two are separate concerns.

The confusion comes from timing. People upgrade Node, then run npm install for the first time in months, hit ERESOLVE, and blame the upgrade. Correlation, not causation. What actually changed is usually one of these:

  • A transitive dependency published a new minor version with a tightened peer range.
  • A lockfile was deleted or regenerated, so npm is resolving fresh instead of replaying pinned versions.
  • A package you added declares a peer range that a package you already have cannot satisfy.

Downgrading Node “works” occasionally because older Node ships an older bundled npm with different resolver defaults, or because the downgrade also reverts the lockfile. That is fixing the symptom by accident. The conflict is still in your tree, waiting for the next npm update.

Read the error before you touch anything, because npm tells you exactly which pair conflicts

The ERESOLVE block always names the package that could not be placed and the two ranges that disagree, so the diagnosis is in the output you already scrolled past. A typical 2026 failure looks like this:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: [email protected]
npm ERR! Found: [email protected]
npm ERR! node_modules/react
npm ERR!   react@"^18.3.1" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^19.0.0" from [email protected]
npm ERR! node_modules/some-chart-lib
npm ERR!   some-chart-lib@"*" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

Three facts are on the table: the root wants React 18.3.1, [email protected] wants React 19 as a peer, and npm will not guess. Now you have options, and the right one depends on which side you can move.

Choose between four fixes based on who owns the incompatible range

Fix the tree, not the toolchain: upgrade the demanding package, upgrade your root package, pin a compatible version of the demanding package, or accept the mismatch with --legacy-peer-deps in that order. Each has a distinct cost.

Upgrade the package that demands the newer peer

If some-chart-lib has a v3 line that peers on React 18, install that instead of forcing the tree:

npm view some-chart-lib versions --json
npm install some-chart-lib@3

This is the cleanest outcome. The peer range was tightened for a reason, usually because v4 uses React 19 APIs that do not exist in 18. Forcing v4 onto React 18 compiles and then fails at runtime, which is worse than a resolver error.

Upgrade the root package to satisfy the peer

If you can move React itself, do it. The peer conflict evaporates because the constraint is now met:

npm install react@19 react-dom@19

Check the migration notes for the major first. A React major is not a drop-in.

Pin the conflicting package to an exact version

When you cannot upgrade either side, pin the demanding package to a version whose peer range matches your tree. Exact pins in package.json are ugly but honest:

"dependencies": {
  "some-chart-lib": "3.8.2"
}

Then regenerate the lockfile deliberately:

rm package-lock.json
npm install

Verify the resolved tree afterward with npm ls react. If it prints more than one version, you did not actually fix it; you moved the conflict one level down.

Use --legacy-peer-deps when the conflict is cosmetic and you accept the risk

This flag tells npm to skip peer-dependency resolution entirely and install what the tree asks for. It is appropriate when the peer range is stricter than reality, for example a library that declares peerDependencies: { "react": "^18 || ^19" } in its next release but shipped a stale range in the version you are on.

Do not set it globally and forget it. A repo-level .npmrc entry makes it permanent and invisible:

# .npmrc
legacy-peer-deps=true

That is the cargo-cult move. Every future install silently ignores peer constraints, including the ones that would have caught a genuine incompatibility before it reached production. If you must use the flag, pass it on the command line so it appears in your terminal history and in CI logs.

What --force does differently, and why it is the wrong default

--force installs the tree even when npm knows it is broken, including overwriting conflicting files on disk, so it can produce a node_modules that no lockfile describes. The npm CLI documentation has distinguished the two flags since the v7 resolver landed: --legacy-peer-deps changes how peers are resolved, --force overrides the refusal to install an inconsistent tree.

In practice, --force is for recovering a corrupted install, not for resolving peer ranges. Reach for --legacy-peer-deps first, and treat --force as a last resort you revert immediately.

Make the fix survive CI, because a local workaround that CI cannot reproduce is not a fix

Any resolution you accept must be encoded in package.json or the lockfile, or your CI runner will hit the same ERESOLVE on a clean checkout. This is the failure mode that costs people hours: it installs on a laptop with a stale node_modules and fails on the first pipeline run.

Two mechanisms make a resolution durable. First, commit the regenerated package-lock.json after any pin or upgrade. Second, if you truly need the flag in CI, put it in the install step explicitly:

# GitHub Actions, npm 11 on Node 22
- uses: actions/setup-node@v4
  with:
    node-version: '22'
- run: npm ci --legacy-peer-deps

Note npm ci, not npm install. npm ci requires a lockfile and installs exactly what it specifies, which is the only way to know your CI and your laptop agree. If npm ci fails with ERESOLVE while npm install succeeds locally, your lockfile is stale relative to package.json. Regenerate it and commit.

For teams that want to see the whole tree at once, npm ls --all prints every resolved version, and npm explain <package> (stable since npm 8) shows why a given version was chosen. Both are read-only and safe to run before deciding anything.

The failure mode to watch for is a green build with a broken runtime

The dangerous outcome is not the ERESOLVE error. It is silencing it with --legacy-peer-deps and shipping a bundle where a library calls an API that does not exist in the React (or Vue, or TypeScript) version actually installed. That surfaces as a blank screen or a TypeError in production, hours after the build passed. If you take the flag, add a smoke test that renders the component using the conflicting library. The resolver warning is cheap; the runtime failure is not.

Related Articles

Similar Posts

Leave a Reply

Your email address will not be published. Required fields are marked *