npm ci Fails but npm install Works

npm ci is designed to install from an existing lockfile without silently updating it. A local npm install can change the dependency resolution, so the two commands are not interchangeable tests. Start with the first real error in the CI log.

Classify the failure

The npm ci documentation explains lockfile requirements and the need to preserve dependency-tree-affecting configuration. A mismatch is one common cause, but not the only one.

First error	Investigation
Manifest and lock disagree	Uncommitted dependency change
Registry authentication	CI credential and registry config
Native package build	OS, architecture and toolchain
Lifecycle script fails	Script environment and required files
Peer dependency resolution	npm version and install settings

Avoid responding to every error by deleting the lockfile. That can replace a reproducibility problem with an uncontrolled dependency update.

Reproduce in a clean environment

Use a disposable checkout of the exact failing commit. Record Node and npm versions, platform and relevant non-secret npm configuration.

Run the same install command as CI. Be aware that npm ci removes an existing node_modules directory; do not run it in a working environment whose installed state you need to preserve without planning for that change.

Keep registry credentials out of logs. Compare configuration names and sources rather than printing tokens.

Repair the correct input

If package.json changed legitimately, regenerate the lockfile using the intended toolchain and settings, review the diff and commit both files together.

If the lockfile was produced with a dependency-tree option, ensure CI uses the required compatible setting. Do not add a broad compatibility flag merely because it suppresses the error; understand the dependency conflict.

For native dependencies, compare the actual platform and build prerequisites. A successful install on a different operating system is weak evidence for the CI environment.

Verify scripts and ignored files

Installation can fail because a lifecycle script expects an untracked local file or environment variable. That is not a lockfile mismatch.

Make the dependency explicit, supply it through the CI configuration or remove the inappropriate install-time requirement. Avoid embedding a developer's machine-specific path into the project.

Confirm reproducibility

Run the clean installation and the relevant build or tests from the corrected commit. Verify that the install leaves package.json and the lockfile unchanged.

When evaluating an AI coding assistant, a fix that merely makes the existing laptop checkout work is incomplete. The acceptance condition is a clean install of the committed project in the intended CI environment.

Related troubleshooting

• Slow npm and Git in WSL Under /mnt/c
• API Key Committed to Git: What to Do Next

This guide draws on the linked documentation. Examples are illustrative unless explicitly identified as measured results.