01
Read the install error before clearing caches
Look for the first useful npm error, not only the pipeline’s final exit code. A missing or invalid lockfile entry is different from a registry authentication error, failed lifecycle script, unavailable package, or TLS problem. Clearing a cache cannot reconcile two committed manifests.
Record the Node and npm versions and the exact CI command. Compare the same repository revision locally. A working development directory may contain packages left over from earlier installs and therefore does not prove that a clean checkout can be installed.
node --version
npm --version
git status --short
# Inspect the manifest changes; do not discard them.
git diff -- package.json package-lock.json .npmrc02
Why npm ci stops instead of repairing the repository
npm ci uses the lockfile as a frozen installation contract. When the dependency declarations disagree with that lockfile, it exits instead of updating it. It also replaces an existing node_modules directory when installing, so run the clean-install check in a disposable checkout if you need to preserve a working directory.
package-lock.json records a resolved dependency tree. A developer may update package.json manually, resolve a merge conflict incorrectly, or forget to commit the generated lockfile. The CI failure is useful evidence that those tracked files no longer form one reproducible input.
03
Repair the lockfile where dependency changes are reviewed
Decide which package.json changes are intentional. If the dependency change is correct, regenerate the lockfile with the project’s chosen npm version and configuration, then review the resulting diff. Do not delete the lockfile just to suppress an error; that can resolve a wider set of versions than the change intended.
A lockfile-only update is a useful option when reconciling metadata without updating the working node_modules tree. It is still a dependency change and deserves review. Check unexpected registry URLs, broad transitive changes, and merge artifacts before accepting it.
# Updates the lockfile, not the working node_modules tree.
npm install --package-lock-only --ignore-scripts --no-audit --no-fund
git diff -- package.json package-lock.json04
Keep tree-shaping configuration consistent
If the lockfile was created with options that affect the dependency tree, npm ci may need the same configuration. The npm documentation specifically calls out cases such as legacy-peer-deps and install-links. Prefer an explicit project-level decision over a developer’s invisible global setting.
Do not add legacy-peer-deps or force merely because an install is failing. Those options can change dependency resolution semantics and mask an incompatible peer relationship. First identify whether the problem is a stale lockfile, mismatched configuration, or an actual dependency conflict.
# Read the relevant effective settings.
npm config get legacy-peer-deps
npm config get install-links
# Inspect the project .npmrc locally; never publish tokens from it.05
Prove the repair in a clean checkout
Commit the intended manifest and lockfile together, then run the actual CI install and project checks in a clean environment. Keep the same dependency options. A successful lockfile-only update does not prove that native modules build or that your application passes its tests.
If CI deliberately omits development dependencies in its runtime stage, keep that separate from the build stage that needs compilers, bundlers, or test tools. Reproducing the whole pipeline is more informative than swapping commands until one local install completes.
# In a disposable checkout of the proposed revision:
npm ci
# Then run the project's real build and test commands.
git diff --exit-code -- package.json package-lock.json06
Keep CI deterministic after the incident
The lasting fix is that a clean install succeeds from the committed inputs without rewriting them. Record the toolchain and dependency settings used to generate the lockfile, and check that future dependency pull requests include the corresponding lockfile changes.
Replacing npm ci with npm install in every build can make this particular error disappear while moving dependency resolution into deployment time. That trades a visible mismatch for a less predictable artifact. Repair the input contract instead.
Sınırları bil
This applies to npm projects with a supported package-lock.json or npm-shrinkwrap.json. Workspaces, private registries, lifecycle scripts, and native dependencies can add separate failures. Commands that install dependencies can execute project scripts unless explicitly disabled.
Kaynaklar ve ileri okuma
CoreTrailKit tarafından hazırlanan teknik yayın.
Bütün yazıları keşfet