All jobs

Fix npm "ERESOLVE unable to resolve dependency tree" Without legacy-peer-deps

Yes. An agent finds which peer dependency ranges conflict, fixes the cause or proves the legacy-peer-deps workaround is no longer needed, and opens a pull request.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The message ends with its own bad advice: retry with --force or --legacy-peer-deps "to accept an incorrect (and potentially broken) dependency resolution". Most projects take it, usually by committing legacy-peer-deps=true to .npmrc, and from then on npm stops checking peer ranges for every package, not only the pair that conflicted. The agent treats that file as the starting point. In an app like alfg/ffmpeg-commander, .npmrc holds the flag under a three-line comment explaining it: ts-jest 27 has a peer dependency on TypeScript below 5, the project uses TypeScript 5, and ts-jest is installed only to satisfy a check in @vue/vue2-jest.

Then it checks the explanation against the manifest. package.json in that repository now lists react and react-dom 19, vite, vitest and typescript at ~6.0.2. There is no ts-jest, no @vue/vue2-jest, no Jest at all, and the jest.config.js the comment points to does not exist. The conflict the flag was added for left with a framework change, and the flag stayed. A comment cannot prove that, so the agent runs the resolver: it removes .npmrc in a scratch copy, deletes the lock file and runs npm install --package-lock-only --strict-peer-deps, which fails on any peer range that is not met. On ffmpeg-commander that resolve completes with no error.

When a conflict is real, the same command prints it, and the agent reads the report instead of the summary line. The scenario in that old comment still reproduces in an empty directory: with typescript at ^5.4.0 and ts-jest at ^27.1.5, npm stops with ERESOLVE, Found: typescript@5.9.3 and Could not resolve dependency: peer typescript@">=3.8 <5.0" from ts-jest@27.1.5. Those two lines name the package that is installed and the range that rejects it. The agent then looks for the smallest change that makes both true: a newer release of the package with the narrow peer range (npm view ts-jest peerDependencies for each major), a lower version of the package it rejects, or, when the peer is declared by a transitive dependency that has no fixed release, an overrides entry scoped to that one package with a note saying when it can be removed.

Last, it applies the result to the real tree. It deletes the flag, runs npm install --package-lock-only against the committed lock and reads the lock diff. In ffmpeg-commander that adds 69 lines, none of them a peer dependency: they are optional packages nested under @tailwindcss/oxide-wasm32-wasi. It runs npm ci and then the steps the workflow in .github/workflows/node.js.yml runs on Node 22 and 24: npm run lint, npm test and npm run build. npm ls at the end confirms no package is reported as invalid or missing.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Fix this project's npm peer dependency conflicts without --force or --legacy-peer-deps. Read package.json, the lock file, .npmrc at every level, and the install commands in CI workflows, Dockerfiles and scripts; list every place legacy-peer-deps, force or strict-peer-deps is set, and quote any comment explaining why. Check whether each package such a comment names is still a dependency. In a scratch copy with those settings removed and the lock file deleted, run npm install --package-lock-only --strict-peer-deps and report the result. If it fails, quote the Found and Could not resolve lines of every ERESOLVE report, and for each conflict name the package installed, the package whose peer range rejects it, and whether that package is a direct or transitive dependency. For each conflict choose the smallest fix in this order: a release of the rejecting package whose peer range accepts the installed version (check with npm view); a version of the installed package inside the range, only if nothing in the project needs the newer one; an overrides entry scoped to that one package when no fixed release exists, with a comment in the pull request saying what would let it be removed. Never widen the fix to the whole tree. Then remove the workaround settings from the real tree, update the lock file with npm install --package-lock-only, and summarise the lock diff by package. Run npm ci, npm ls, and every lint, test and build script that CI runs, on the Node versions CI uses. If the strict resolve passes with no changes, say that the workaround is no longer needed and remove it. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

A pull request whose size depends on what the resolver said. For a project where the conflict is gone, it deletes .npmrc and updates package-lock.json, and the description shows the comment that justified the flag next to the evidence that its subject left the project: the package names searched for in package.json and the lock, and the output of the strict resolve. For a project with a live conflict, it changes one or two version ranges or adds one scoped overrides entry, and quotes the ERESOLVE report it fixed.

The reviewer checks that the flag is gone from every place it was set, since a workflow that runs npm ci --legacy-peer-deps keeps the old behaviour whatever .npmrc says. They read the lock diff summary for packages that appeared: with peer checking back on, npm installs peers it used to skip, and a new package in the tree is worth a look. They also confirm the checks ran on each Node version the workflow lists.

Run it on every install step that fails with ERESOLVE

The conflict usually shows up on a dependency update, often one opened by a bot. An automation's github trigger never fires for a bot sender, so do not rely on pull_request.opened for those. Give the automation a webhook trigger instead and call it from the workflow: add a step that runs only when the install step failed and its log contains ERESOLVE, and have it POST the branch name and the failing lines to the trigger's URL with Authorization: Bearer and the trigger's secret, which you keep as a repository secret.

Whatever that step posts, up to 64 KB, is placed after the saved prompt as the event. Send an Idempotency-Key header to the trigger's URL, set to the workflow run id, so a re-run of the failed job starts nothing new. The call answers 202 with the outcome of the fire and the execution_id of the run it created. Set the automation's max runs per hour low: one broken update can fail many workflow runs in a row.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

Why run it on Rush?

This is a question for the resolver, and the resolver has to run somewhere with a clean cache and no local overrides. A laptop often has a user-level .npmrc with its own settings, which is how a conflict gets reported as fixed and then fails in CI. The run resolves the tree in its own sandbox from the repository's files alone, on the Node versions the workflow names, and keeps the full output of each attempt in the session transcript.

It also makes the case for removing a setting people are afraid to touch. Nobody deletes legacy-peer-deps=true on a hunch, because the failure it once hid was painful. A strict resolve from an empty lock, followed by the project's own lint, test and build, is the evidence that lets a reviewer approve the deletion, and it is in the pull request.

Frequently asked questions

Is it safe to just keep legacy-peer-deps=true?

It works until it does not. The setting tells npm to ignore peer ranges for every package, so a later upgrade can install a plugin next to a host version it does not support and nothing warns you. It also stops npm from installing peers automatically, which is how a clean checkout ends up missing a package that a developer happens to have.

How do I read an ERESOLVE report?

Look for two blocks. Found: names the version npm has chosen for a package and who asked for it. Could not resolve dependency: names a second package and the peer range it declares, which the found version falls outside. The fix is to change one of those two so the range is met.

When is an overrides entry the right fix?

When the package with the narrow peer range works fine with the newer version and has not published a release that says so. Scope the override to that package, for example the peer of one named dependency, and record what to watch for so it can be removed. An override at the top level that forces a version everywhere is the same blunt tool as the flag.

What is the difference between --force and --legacy-peer-deps?

--legacy-peer-deps makes npm ignore peer dependencies completely, as npm 6 did: it neither checks nor installs them. --force keeps resolving peers but accepts a conflicting result and overrides other protections too. Both produce a tree npm itself describes as potentially broken.

The agent found no conflict. Why was the flag there?

Usually because the dependency that caused it was upgraded or removed later and nobody revisited the setting. In ffmpeg-commander the comment beside the flag describes a Jest and Vue 2 setup, and the project has since moved to React and Vitest. Removing the flag then is the whole fix, backed by a strict resolve that passes.

More jobs like this: Upgrade dependencies weekly

Keep reading