npm ERESOLVE: align peer dependency versions

Extract the conflicting relationship

Find the lines identifying the installed or requested host version, the package declaring the peer, and its required range. A peer dependency describes a compatibility expectation for the environment in which a package is used.

Our controlled app selected fixture-host 1.0.0 while fixture-plugin declared ^2.0.0. npm rejected that combination with ERESOLVE. Both packages came from local tarballs, so this test did not depend on an unavailable registry or credentials.

Read the declaring package’s contract

The following fragment shows the synthetic plugin’s peer requirement. It is illustrative package metadata; these fixture names are not packages you should install from the public registry.

For a real dependency, compare the published version’s metadata and compatibility guidance. A range that installs successfully is one requirement, while correct behavior of the integration remains a separate check.

json · EXAMPLE

{
  "name": "fixture-plugin",
  "version": "1.0.0",
  "peerDependencies": {
    "fixture-host": "^2.0.0"
  }
}

Choose a compatible combination deliberately

If the application can use the required host major version, review that upgrade and its migration requirements. Otherwise select a plugin release that supports the application’s host, if such a supported combination exists.

In the fixture, we changed the application’s local host dependency to version 2.0.0 and kept the plugin’s peer metadata intact. We did not edit a third-party package’s constraint or use force or legacy-peer-deps to suppress the conflict.

Inspect the resulting tree

After the intended manifest change, install using the project’s reviewed configuration and inspect the selected versions. npm explain is useful for tracing an installed dependency; it is not a substitute for the original failure report when no install tree exists.

These read commands use the local fixture names as examples. Replace them with the actual packages under investigation. Do not paste private registry credentials from npm configuration into diagnostics.

sh · EXAMPLE

npm ls fixture-host fixture-plugin
npm explain fixture-host

Verify the integration after resolution

The corrected fixture installed and the plugin returned the host’s expected major version. That checked a minimal load path in addition to npm’s successful exit status.

For an application, run its real integration, build, and test checks against the resulting lockfile. A solver-compatible tree does not prove a framework upgrade is safe. Preserve the selected versions and the verification result with the reviewed dependency change.

Know the limits

Reproduced with npm 12.2.1 and Node.js 24.22.1 in a disposable Linux container using local fixtures, with external networking disabled during tests. A plugin required host version ^2.0.0 while the app selected a local 1.0.0 tarball. Selecting the compatible 2.0.0 fixture resolved the install and the plugin loaded. Real registry selection, framework compatibility, and third-party application behavior were not tested.

Sources & further reading

A technical publication by CoreTrailKit.

Browse all articles