npm ERR! ERESOLVE: Unable to Resolve Dependency Tree

Why npm stops here

peerDependencies express a compatibility relationship with a host package. npm's package.json documentation notes that peer dependencies are installed by default from npm v7 onward and conflicting requirements can prevent npm from resolving a valid tree. The useful question is therefore not “How do I bypass ERESOLVE?” but “Which declared compatibility ranges cannot coexist under the npm version, workspace scope and effective resolver configuration actually running this install?”

Fix #2 — root package version is outside the peer range

If your project directly declares both sides, find a version relationship the package authors actually declare as compatible. For example, if a plugin declares peerDependencies: {"host":"^2"}, installing host 3 does not satisfy that contract merely because both packages install individually.

Check the plugin/library release notes and package metadata before choosing which side to move. Read semver ranges precisely: ^2.3.0 generally permits compatible releases below 3.0.0, but caret ranges below 1.0.0 are intentionally narrower—for example ^0.2.3 does not mean “any 0.x”. Pre-release versions also have special matching rules. When in doubt, evaluate the exact range printed by npm rather than translating every caret to “same major”.

A newer plugin may support the host version you need; alternatively your project may intentionally need the older host until its ecosystem catches up.

Verify: Run the install normally—without bypass flags—then inspect the pair with npm ls host plugin. npm should no longer report that relationship as invalid. Run the relevant build/test afterward.

Fix #3 — an upgrade changed the peer contract

If ERESOLVE appeared immediately after upgrading a framework, plugin or tool, compare the old and new package's peer ranges. Do not assume “latest + latest” is always a compatible pair: release timing and major-version support can differ across packages.

Verify: The chosen versions have overlapping declared compatibility, normal npm install succeeds, and the feature/build that uses the plugin still passes.

Fix #4 — transitive, workspace or monorepo conflict: find who owns the edge

Do not immediately add the transitive package to your root package.json. In npm workspaces/monorepos, first identify which workspace declares the host, which workspace/plugin declares the peer, and whether the install is being resolved from the workspace root. A conflict surfaced at the root can still belong to one workspace's dependency contract.

If the package is already installed, npm explain <package> shows chains that caused that installed package to be present; npm ls <package> --all shows installed versions and invalid/missing relationships. With workspaces, scope your inspection to the relevant workspace when useful instead of assuming the root tree tells the whole ownership story.

npm explain explains the installed tree; it is not a reconstruction of the resolver's failed hypothetical tree. If install fails before a usable tree exists—or node_modules reflects an older install—its output may be absent or describe stale state. In that case rely on the current ERESOLVE conflict block plus the relevant workspace/root manifests and lockfile, then inspect the dependency that owns the incompatible range.

Verify: You can identify the direct/workspace dependency that introduces the conflicting package, then fix that owner's version relationship rather than masking it at the root.

Fix #5 — package.json vs package-lock.json: do not delete the lockfile reflexively

The lockfile records npm's resolved dependency graph and metadata for reproducible installs. If package.json changed, first decide whether the new manifest requirement is intentional. Compare the relevant dependency entries and your version-control diff before deleting or regenerating anything. Also distinguish npm install from npm ci: npm ci requires an existing lockfile and exits instead of rewriting it when the lockfile and manifest are out of sync.

Verify: commit/review the manifest and lockfile together. Reproduce the workflow your project actually depends on—often npm ci in CI—using the intended Node/npm version, workspace scope and project resolver configuration. npm documents that if a lockfile was created with flags that materially shape the dependency tree, such as --legacy-peer-deps or --install-links, npm ci needs equivalent configuration; committing the relevant project .npmrc can make that policy reproducible. A local npm install that silently rewrites the lockfile is not enough evidence for a CI fix.

Fix #6 — why --legacy-peer-deps and --force are not the default fix

npm documents legacy-peer-deps as completely ignoring peerDependencies while building the package tree, and explicitly says its use is not recommended because it does not enforce the peer-dependency contract. That can be useful as a temporary diagnostic or migration escape hatch, but a successful install does not prove the packages actually work together.

--force also removes npm protections and should not replace understanding the conflict. Likewise, check whether legacy-peer-deps, strict-peer-deps, workspace selection, or related install settings are already coming from CLI flags, environment or .npmrc; otherwise two developers can appear to run “npm install” while invoking different resolver policy. If a controlled environment temporarily requires a bypass, record that unresolved contract and test the affected integration explicitly.

Verify: the intended durable policy is explicit and reproducible. Prefer a normal install without a peer-contract bypass; confirm npm ls does not report the target relationship invalid and run build/tests covering the integration. If a temporary migration policy intentionally uses a bypass, do not call the peer conflict resolved—record the policy and remaining compatibility debt.

What about package.json overrides?

npm overrides can be appropriate when the root project intentionally needs to replace a dependency deeper in the tree—for example to use a known-fixed transitive release, keep one dependency version consistent, or replace a package with a fork. npm applies overrides from the root package.json.

Also note npm's restriction on overriding a package you directly depend on: the override must match the direct dependency spec unless you reference that direct spec using npm's supported $name form. If your real problem is two direct packages with incompatible peer contracts, align those direct versions instead of using overrides as camouflage.

Verify an override: inspect the resulting tree with npm ls/npm explain, review the lockfile diff, run a clean npm ci where applicable, and run tests that exercise the dependency you replaced.

Still seeing ERESOLVE?

Capture the first actionable conflict from the current failing resolver run. Later conflicts may be downstream effects, and fixing the first pair can reveal a new next conflict. If npm wrote an ERESOLVE report, use it as evidence, but correlate it with the command/version/configuration that produced it rather than mixing it with an older node_modules tree or another install attempt.

Official references