why does npm ci sometimes fail with ERESOLVE even when package-lock.json is already committed and matches package.json? for example, a project works locally with npm install, the lockfile is committed, but a clean environment running npm ci fails with a peer dependency conflict. what exactly does npm ci validate differently from npm install, and what is the correct way to fix the lockfile without simply using --legacy-peer-deps or --force?

[Ram-0777]

I’m trying to understand something about npm dependency resolution.

I have a project where npm install works normally, but running npm ci in a clean environment can fail with an ERESOLVE peer dependency conflict, even though package.json and package-lock.json are both committed.

What exactly does npm ci validate differently from npm install in this situation?

Also, what would be the proper way to fix the dependency tree and regenerate the lockfile? I’d prefer to understand and resolve the actual conflict rather than using --legacy-peer-deps or --force.

Thanks.

[krishanth7]

I think the important distinction here is that npm install and npm ci are not intended to behave exactly the same way when resolving dependencies.

npm install is allowed to resolve dependencies and update package-lock.json when necessary. npm ci, on the other hand, is designed for clean and reproducible installs. It expects the lockfile to already describe a dependency tree that can actually be installed under the current npm configuration. It does not use npm ci as an opportunity to casually rewrite the lockfile.

So it is possible for this to happen:

package.json
      ↓
npm install
      ↓
dependency resolution succeeds
      ↓
package-lock.json gets updated

while a clean environment using:

npm ci

fails with something like:

ERESOLVE unable to resolve dependency tree

A common reason is a peer dependency conflict. For example, suppose one package requires:

react ^18

while another package in the same dependency tree declares a peer requirement such as:

react ^17

The issue isn't necessarily that the lockfile is "corrupted". The problem may be that the dependency graph contains requirements that npm cannot satisfy consistently under the current resolver/configuration.

What I would check first

I would start by checking the exact versions of npm and Node being used locally versus in the clean environment:

node --version
npm --version

Also check whether the project has an .npmrc file or CI configuration containing options that affect dependency resolution.

Then inspect the dependency tree:

npm ls

and, for a particular package:

npm ls <package-name>

For peer-dependency information, this can also be useful:

npm explain <package-name>

The goal is to identify which package requires which version rather than treating the ERESOLVE message as the problem itself.

The proper way to fix it

Once the conflicting packages are identified, I would fix the dependency declarations first.

For example, if package A requires:

some-library ^2.0.0

but package B only supports:

some-library ^1.0.0

then the real solution is to find compatible versions of A and B, upgrade/downgrade one of them, or replace the incompatible package if necessary.

After resolving the actual version conflict, regenerate the lockfile using the same Node/npm environment that will be used in CI:

rm -rf node_modules package-lock.json
npm install

Then verify the result from a completely clean install:

rm -rf node_modules
npm ci

If npm ci succeeds after that, commit the resulting package-lock.json.

I would not use --legacy-peer-deps or `--force as the first solution. Those options can be useful in specific situations, but they can also hide the dependency conflict instead of fixing the underlying package compatibility problem.

One other thing worth checking is whether the lockfile was generated with special npm settings. npm's documentation notes that certain dependency-resolution flags used when creating the lockfile may also need to be used when running npm ci; otherwise the clean install can fail even though the lockfile itself is committed.

So, in practice, my debugging order would be:

1. Compare Node and npm versions
2. Check .npmrc and CI npm configuration
3. Read the complete ERESOLVE output
4. Identify the exact peer dependency conflict
5. Check the dependency tree with npm ls / npm explain
6. Choose compatible package versions
7. Regenerate package-lock.json
8. Delete node_modules
9. Run npm ci from a clean environment
10. Commit the verified lockfile

The key point is that a committed package-lock.json does not automatically mean the dependency graph is conflict-free. The lockfile records the resolved tree, but npm still has to validate that tree against the package metadata and the installation configuration being used.

If the exact ERESOLVE output is available, that would make this much easier to diagnose. The most useful part is usually the section showing Found: and Could not resolve dependency:, because that tells you exactly which package versions are conflicting.

[sauravkumarpanda7-cm]

I think the important distinction here is that npm install and npm ci are not intended to behave exactly the same way when resolving dependencies.

npm install is allowed to resolve dependencies and update package-lock.json when necessary. npm ci, on the other hand, is designed for clean and reproducible installs. It expects the lockfile to already describe a dependency tree that can actually be installed under the current npm configuration. It does not use npm ci as an opportunity to casually rewrite the lockfile.

So it is possible for this to happen:

package.json
      ↓
npm install
      ↓
dependency resolution succeeds
      ↓
package-lock.json gets updated

while a clean environment using:

npm ci

fails with something like:

ERESOLVE unable to resolve dependency tree

A common reason is a peer dependency conflict. For example, suppose one package requires:

react ^18

while another package in the same dependency tree declares a peer requirement such as:

react ^17

The issue isn't necessarily that the lockfile is "corrupted". The problem may be that the dependency graph contains requirements that npm cannot satisfy consistently under the current resolver/configuration.

What I would check first

I would start by checking the exact versions of npm and Node being used locally versus in the clean environment:

node --version
npm --version

Also check whether the project has an .npmrc file or CI configuration containing options that affect dependency resolution.

Then inspect the dependency tree:

npm ls

and, for a particular package:

npm ls <package-name>

For peer-dependency information, this can also be useful:

npm explain <package-name>

The goal is to identify which package requires which version rather than treating the ERESOLVE message as the problem itself.

The proper way to fix it

Once the conflicting packages are identified, I would fix the dependency declarations first.

For example, if package A requires:

some-library ^2.0.0

but package B only supports:

some-library ^1.0.0

then the real solution is to find compatible versions of A and B, upgrade/downgrade one of them, or replace the incompatible package if necessary.

After resolving the actual version conflict, regenerate the lockfile using the same Node/npm environment that will be used in CI:

rm -rf node_modules package-lock.json
npm install

Then verify the result from a completely clean install:

rm -rf node_modules
npm ci

If npm ci succeeds after that, commit the resulting package-lock.json.

I would not use --legacy-peer-deps or `--force as the first solution. Those options can be useful in specific situations, but they can also hide the dependency conflict instead of fixing the underlying package compatibility problem.

One other thing worth checking is whether the lockfile was generated with special npm settings. npm's documentation notes that certain dependency-resolution flags used when creating the lockfile may also need to be used when running npm ci; otherwise the clean install can fail even though the lockfile itself is committed.

So, in practice, my debugging order would be:

1. Compare Node and npm versions
2. Check .npmrc and CI npm configuration
3. Read the complete ERESOLVE output
4. Identify the exact peer dependency conflict
5. Check the dependency tree with npm ls / npm explain
6. Choose compatible package versions
7. Regenerate package-lock.json
8. Delete node_modules
9. Run npm ci from a clean environment
10. Commit the verified lockfile

The key point is that a committed package-lock.json does not automatically mean the dependency graph is conflict-free. The lockfile records the resolved tree, but npm still has to validate that tree against the package metadata and the installation configuration being used.

If the exact ERESOLVE output is available, that would make this much easier to diagnose. The most useful part is usually the section showing Found: and Could not resolve dependency:, because that tells you exactly which package versions are conflicting.

[TheVingance]

Hi @Ram-0777,

The fundamental reason this happens lies in how npm's dependency engine (Arborist) treats tree mutation vs. tree validation.

Why npm install passes while npm ci fails on the same lockfile

• npm install is permissive and mutative:
  When running npm install, npm evaluates the dependency graph with permission to resolve ambiguities on the fly. If an existing node_modules directory exists or if sub-dependencies have conflicting peer contracts, the resolver often creates nested fallbacks or tolerates non-fatal discrepancies without failing the build.

• npm ci enforces an immutable, top-down tree check:
  npm ci completely bypasses dependency resolution heuristic workarounds. It loads package-lock.json directly into memory and performs a strict assertion: every peer dependency constraint in the entire tree must be satisfied without altering a single node. If your lockfile was generated incrementally across multiple npm install runs, minor Node/npm CLI version discrepancies, or with dirty caches, the lockfile can contain validly resolved tarballs that nonetheless violate top-level peer rules when evaluated strictly from scratch.

• npm CLI Version & Lockfile Specs:
  If the lockfile was generated with npm v8/v9 and CI runs npm v10 (or vice versa), the strictness of the Arborist peer resolution algorithm differs, causing ERESOLVE during the strict verification stage.

---

How to fix the lockfile properly (without --legacy-peer-deps or --force)

Instead of bypassing peer checks, resolve the conflict declaratively within your project:

1. Trace the conflicting peer tree

Run:

npm explain <conflicting-package>
# or
npm ls <conflicting-package>



Look at the `ERESOLVE` block: it explicitly states which parent package is enforcing an outdated peer dependency version range.

#### 2. Address the conflict declaratively

Depending on where the conflict lives:

* **Direct dependency:** Upgrade or align the package causing the peer restriction in your `package.json`.
* **Transitive / nested dependency:** If an upstream library has not yet published an updated release supporting the new peer version, use native npm **`overrides`** in your `package.json` to enforce consistency across the entire tree:
```json
{
  "overrides": {
    "conflicting-library": "$conflicting-library"
  }
}

(This avoids --legacy-peer-deps entirely and keeps your dependency tree deterministic.)

3. Rebuild the lockfile from a clean slate

Ensure you are using the same major Node and npm versions as your CI pipeline, then execute:

# Clean local state completely
rm -rf node_modules package-lock.json

# Re-resolve and build the new deterministic lockfile
npm install

# Verify that strict verification passes
npm ci

Once npm ci exits with code 0 locally in a clean run, commit the new package-lock.json.

---

If this breakdown helped clarify the resolution process and resolved your CI issue, please consider marking this as the accepted answer!

[1soka]

The thing I'd check first: is legacy-peer-deps turned on in your local npm config? It's easy to set once and forget about it.

npm config get legacy-peer-deps
npm config ls -l | grep -i peer

If it says true (often from ~/.npmrc), your local npm install never checks peer deps and the lockfile gets written without them. The CI starts with a clean config, so npm ci checks them strictly and hits the conflict. Same story if your local npm is v6 and the CI uses 7+ (compare npm -v on both).

To fix the real conflict, read the ERESOLVE block, it names the culprit, something like peer react@"^18" from some-lib@2.1.0. Then look for a version of that lib that accepts what you have:

npm view some-lib peerDependencies
npm view some-lib@3 peerDependencies

Upgrade it (or align the other side), then rebuild the lock with the flag off:

npm config delete legacy-peer-deps   # or remove the line from the .npmrc that sets it
rm -rf node_modules package-lock.json
npm install
npm ci                               # should now pass locally, same as CI

overrides is only worth it if no compatible version exists. Pinning Node in CI (.nvmrc + node-version-file in setup-node) also avoids getting a different npm there.

[metopism]

The difference is that npm install is allowed to resolve conflicts on the fly and update the lockfile as it goes, while npm ci treats the lockfile as gospel and fails hard if reality doesn't match it. So if your lockfile was generated in an environment where --legacy-peer-deps was set in your .npmrc, or on a different npm version that was more lenient about peer conflicts, the lockfile can contain a tree that a stricter environment refuses to install from.

To actually find the conflict rather than suppress it, run npm install --dry-run locally without any legacy flags and let it surface the ERESOLVE. npm will tell you exactly which package is requesting a peer that conflicts with what's installed. From there you're looking for one of three situations — a package that hasn't updated its peer dep declarations to match the version you're actually using, two packages that need incompatible versions of the same peer, or a transitive conflict where something nested is pulling in a version that fights with a top-level dep.

Once you've identified the actual conflict the clean fix is usually pinning the problematic package to a version whose peer dep range is compatible with everything else, or checking whether a newer version of it has relaxed the peer requirements. After that delete node_modules and package-lock.json, run a fresh npm install without any flags, verify it resolves cleanly, and commit the regenerated lockfile. That lockfile will then pass npm ci in a clean environment because the tree it describes is genuinely valid.

[moustafax7-dotcom]

Hi @Ram-0777 ,

A useful way to troubleshoot this is to treat it as a dependency compatibility vs. environment consistency problem.

One important distinction: npm ci does not simply validate that package.json and package-lock.json exist or appear synchronized. It performs a clean installation using the lockfile, without updating it. The dependency tree must also be installable under the npm version and configuration being used.

I'd recommend this diagnostic sequence:

1. Compare npm configurations

Run these locally and in CI:

node --version
npm --version
npm config get legacy-peer-deps
npm config get strict-peer-deps
npm config get install-strategy

Also check whether a user-level .npmrc is affecting local installs but is missing from CI.

2. Identify the actual conflict

Inspect the complete ERESOLVE output, especially the Found: and Could not resolve dependency: sections.

Then check the relevant package:

npm explain <package-name>
npm view <package-name>@<version> peerDependencies

3. Fix compatibility before regenerating the lockfile

Choose dependency versions with compatible peer requirements. If a package only supports React 18, for example, installing React 19 will not become valid simply by regenerating package-lock.json.

4. Verify reproducibility

After fixing the dependency declarations, use the same npm version and resolution settings as CI:

npm install --package-lock-only
npm ci

If npm ci succeeds in a clean environment, commit the updated manifest and lockfile together.

I would avoid deleting the lockfile as the first troubleshooting step because doing so can introduce unrelated dependency upgrades and make the original conflict harder to diagnose.

The key takeaway: A committed lockfile provides reproducibility only when the dependency declarations, npm configuration, and relevant toolchain behavior are compatible.

If you can share the exact ERESOLVE output and the npm versions used locally and in CI, it should be possible to identify the specific conflicting peer dependency.