npm ERESOLVE: --legacy-peer-deps vs --force (What Each Really Does)
npm has two messages with "ERESOLVE" in them, and they're easy to mix up. One is an error and the install stops. The other is a warning and the install carries on. The usual advice for both is "add --legacy-peer-deps " or "add --force ", but the two flags don't do the same thing, and neither one fixes the conflict. I wanted to see exactly what each option does, so on 20 November 2026 I built a…
npm ERESOLVE comes in two forms: an error that halts installation, and a warning that allows the process to continue. Both flags, --legacy-peer-deps and --force, are often suggested as solutions, but they do not address the underlying conflict. To illustrate the distinct actions of each flag, a local test was conducted on November 20, 2026, using npm version 10.9.2.
The error mode is triggered when npm is unable to resolve the dependency tree. In this scenario, the error message reads: "Could not resolve dependency: peer kmg-lib@ ^1.0.0 from kmg-plugin@1.0.0." The message identifies the package with the strict peer requirement (kmg-plugin@1.0.0) and the found package (kmg-lib@2.0.0). The bottom-up reading of the output reveals that npm refuses to pick a side when both packages are direct dependencies, resulting in the error and exit code 1.
The warning advises retrying the command with either --force or --legacy-peer-deps to accept an incorrect dependency resolution.
The warning mode is generally encountered without any explicit command. For example, during an npx n8n installation, 32 warnings appeared before the installation successfully completed with an exit code of 0. The warning message reads: "While resolving: @ai-sdk/anthropic@2.0.61, Found: zod@3.25.67, Could not resolve dependency: peer zod@ ^3.25.76 || ^4.1.8 from @ai-sdk/anthropic@2.0.61."
This indicates that npm has chosen a version for the package that falls outside of its stated peer range. The default behavior described in npm's documentation is to resolve deep conflicts using the nearest non-peer dependency specification, resulting in a warning being printed.
The --legacy-peer-deps flag works by completely ignoring peerDependencies while building a package tree. When applied, npm installs the packages without regard to peer dependencies, resulting in the installation working with an exit code of 0. However, the flag is not recommended, as it hides future peer conflicts and overrides them.
The --force flag, on the other hand, does not ignore peer dependencies, but instead overrides the conflict. This flag also disables recommended protections, allowing the installation of packages with different Node or npm versions, bypassing semver ranges, and installing conflicting peer dependencies in the root project. While --force can get past a peer conflict, it is the broader option and does not provide a clean resolution to the underlying issue.
The most effective solution is to upgrade the package containing the strict peer range, as demonstrated by adding a kmg-plugin@2.0.0 with a peer range of ^1.0.0 || ^2.0.0, which installed cleanly without any flags.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.