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!