Lockfile drift after a dependency upgrade: diagnose before deleting cache

Lockfile drift happens when package metadata, installed modules, and the committed lockfile stop describing the same dependency graph.

The tempting response is to delete the CI cache and rerun. That may be necessary later, but it should not be the first diagnostic move. A cache delete can make the build green while leaving the real mismatch unexplained. Before clearing anything, capture the package manager, lockfile version, install command, and the exact dependency that changed.

The most common pattern is a developer running a flexible local install, committing package.json or pyproject changes, and forgetting the lockfile. Another pattern is a package manager upgrade that rewrites lockfile format. A third is platform-specific optional dependencies: the lockfile may include entries that behave differently across macOS, Linux, Windows, or different CPU architectures.

A useful check is to run the CI install command locally from a clean checkout. For npm this might be npm ci rather than npm install. For pnpm it may be a frozen lockfile install. For Python it may mean rebuilding the virtual environment from the same constraints file. The goal is to reproduce CI’s strictness, not your usual local convenience.

If the strict install fails, update or regenerate the lockfile intentionally and review the diff. If the strict install passes locally but fails in CI, compare platform, registry access, cache key, and package manager version. Do not mix all fixes in one commit; otherwise the next person cannot tell whether the lockfile, cache, or runtime actually caused the failure.

The rule is simple: cache is a suspect, not a confession. Prove the dependency graph first.

Lockfile drift after a dependency upgrade: diagnose before deleting cache

// COMMENTS

ON THIS PAGE