Home/Troubleshooting guide
npm dependency guide

npm ERESOLVE: read the conflict before changing versions

Short answer: save the error and environment, extract four conflict fields, trace the requesting chain, and test the smallest supported version alignment in a clean checkout.

Unbranded laptop showing an abstract dependency graph with one amber conflict path on a quiet desk
Short answer: Preserve the full ERESOLVE report, then identify the selected package, selected version, peer package, and required peer range. Use npm explain or npm ls to find the requesting chain. Use npm view to read the published peer range for one proposed version. Choose the smallest change that satisfies the declared ranges and the project's own support rules. Review the manifest and lockfile diff, then run the expected install, build, and tests in a clean temporary checkout.
Do not erase the evidence first. Do not delete package-lock.json, node_modules, or the npm cache before saving the error, versions, configuration boundary, and version-control state. Do not use --force or --legacy-peer-deps as the default fix. A successful bypass does not prove that the package combination is compatible.

Confirm that the error is ERESOLVE

npm uses several error codes for different failures. This guide is for an install that exits with ERESOLVE and says it cannot resolve the dependency tree or could not resolve a dependency. Keep these failures separate:

  • ETARGET means the requested version does not exist in the selected registry.
  • E401 or E403 points to authentication or authorization.
  • ENOENT points to a missing file or path.
  • A command that never exits is a hang, not an ERESOLVE exit.
  • A later build, test, or runtime failure occurs after dependency resolution.

Save the complete terminal output and the npm report path before making a change. Record the operating system, output of node --version and npm --version, the exact npm command, current branch, workspace, and selected registry hostname. Do not post registry tokens, private package names, repository URLs, proprietary manifests, or full internal logs in a public issue.

Save the project state

Check version control before touching the dependency tree. Preserve package.json, package-lock.json, workspace manifests, project .npmrc, and any overrides or package extensions. If the working tree is already dirty, record those changes so a dependency edit does not absorb unrelated work.

Do not assume the lockfile is disposable. npm uses exact lockfile versions when they still satisfy the manifest ranges. Removing the lock can select a different set of transitive versions and turn one peer conflict into a much larger review.

Keep user and global npm configuration out of shared evidence unless the project needs a specific setting. Never paste an authentication token or a complete private registry configuration into a ticket, chat, or public reproduction.

Read four fields from the report

The report often feels longer than the decision it describes. Reduce the relevant block to four fields:

  1. Selected package. The package npm is trying to place.
  2. Selected version. The version already chosen or requested.
  3. Peer package. The package that must be supplied by the surrounding project.
  4. Required peer range. The version range declared by the requesting package.

Read the Found and Could not resolve dependency lines together. A conflict such as one package requiring a peer in the 4.x range while the project selects 5.x is a declared contract mismatch. The error does not decide whether the project should move the direct dependency, the peer, or another package in the requesting chain.

Do not choose a version from the error text alone. The project may have framework, runtime, browser, operating-system, support, or release rules that are stricter than the published peer range.

Trace why the package is present

If an installed tree exists, run npm explain <package>. npm documents this command as a way to print the chain that caused a package to be installed. Use the exact package named in the conflict. A package at a specific path can also be explained when duplicates exist.

npm ls <package> shows the logical installed tree and can mark missing, invalid, or extraneous entries. Treat it as evidence when a tree exists. A failed first install may not leave a complete tree, so an empty or partial result is not another failure to repair.

For one proposed version, run npm view <package>@<version> peerDependencies. That reads the peer range published in the registry metadata. It does not prove that the version works with the rest of the project, only what the package declares.

Check the root manifest, workspaces, overrides, package extensions, and project npm configuration. The same package names can resolve differently when any of those inputs change.

Choose the smallest supported alignment

Start with the package that owns the incompatible range. Review its current release notes and support table when available. The safest change is usually the narrowest supported alignment that satisfies the peer contract and the project's release rules.

Common decisions include keeping the selected peer and choosing a compatible requester version, or moving the peer only after every direct consumer supports it. An override may be appropriate when the project deliberately owns that exception, but it should be documented, reviewed, and removable. Do not add an override simply to hide a conflict you have not traced.

--legacy-peer-deps makes npm ignore peerDependencies while building the tree. npm does not recommend it because the resulting tree does not enforce the peer contract. --force can also accept a combination that needs review. Either flag can be useful in a controlled reproduction, but a zero exit code is not a compatibility result.

Verify in a clean temporary checkout

Make the reviewed manifest change through the project's normal workflow. Inspect every line changed in package.json, package-lock.json, workspace manifests, and project npm configuration. Unrelated transitive churn is a reason to stop and understand the resolver inputs.

Use a clean temporary checkout or the team's normal disposable test environment. Run the install method the project expects. If the repository uses a committed lockfile, npm ci is useful because it fails when the lock and manifest disagree and does not rewrite them.

Then run the project's build, type checks, unit tests, integration tests, and the smallest relevant runtime check. A successful install proves only that npm produced a tree. It does not prove application behavior, security, browser support, deployment support, or compatibility with private packages.

Do not publish a package, change shared CI, or deploy from this diagnostic sequence. Those are separate reviewed actions.

Check the resolver-bug boundary

Current npm issue records include ERESOLVE reports involving transitive or optional peers. They also include a separate October 21 report where installs can hang when no matching version exists and several peers are involved. Similar wording is not enough to call your failure the same npm bug.

Compare the exact npm version, Node.js version, dependency graph, workspace shape, registry, command, clean-versus-in-place state, and exit behavior. If the declared ranges should resolve and a current npm issue matches those details, preserve a minimal reproduction with no secrets. Keep the original project logs separate.

Testing one nearby npm version can help confirm a documented version boundary when the test is isolated and reversible. A global downgrade without a matching issue or project requirement creates another variable and can affect unrelated repositories.

Where OmniMend fits

OmniMend can collect local system, application, update, and timeline evidence on supported hosts. It does not edit package manifests, choose dependency versions, run npm commands for you, publish packages, change CI, or guarantee that an ERESOLVE conflict can be repaired.

The complete guided workflow runs on supported Windows 10 and Windows 11 x64 systems. The Apple Silicon Mac build provides native local diagnostics only. OmniMend does not list a Linux build. If you want a separate non-secret system record beside the npm report, choose the supported OmniMend host. Review and redact the record before sharing it.

For a different developer-tool failure, see the VS Code extension host guide or the Docker Desktop startup guide. Those pages do not own npm peer-range conflicts.

Editorial sources

Checked October 22, 2026 against npm's current documentation for npm explain, npm ls, npm view, npm install, npm ci, and legacy-peer-deps. Current npm CLI issues #10054 and #10149 define narrow bug and hang boundaries. They do not prove that another project's graph has the same resolver defect. OmniMend added the four-field reading method, state-preservation order, privacy limits, internal routing, and product boundary. This page does not select a package version, approve a bypass, or claim that OmniMend resolves dependencies.

Read the conflict.
Change the smallest input.

Preserve the npm report and project state. Use OmniMend only if a separate local system record would help on a supported host.

Get OmniMend