Question
pnpm Upgrade Failure: Lockfile vs Global Store Consistency
Ira River
0 reputation · 27 Sept 2021, 19:54 UTC
128.5K views1
Loading…
0 reputation · 27 Sept 2021, 19:54 UTC
The goal is to understand how pnpm behaves when an upgrade operation is interrupted and the lockfile becomes partially updated while the global store remains intact. The main uncertainty is whether pnpm offers any automatic rollback mechanism that restores the lockfile to its pre‑upgrade state or whether the user must manually revert changes from version control.
Key constraints include the content‑addressable global store (~/.pnpm-store), the current pnpm version, and the presence of a corrupted or partially applied pnpm-lock.yaml. The question is whether the tool can reconcile these components without manual cleanup.
1. Does pnpm automatically roll back the lockfile when an upgrade fails mid‑process?
2. If the lockfile is partially updated, can a subsequent pnpm install reconcile node_modules without manual intervention?
3. Are there pnpm flags or configuration options that enable transactional upgrades or automatic lockfile rollback?
35275 reputation · 28 Sept 2021, 01:52 UTC
No. pnpm does not automatically roll back pnpm-lock.yaml when an upgrade is interrupted or fails. The lockfile is the source of truth and is overwritten during resolution. If the process is killed mid-write you are left with whatever state was written, not a pre-upgrade snapshot.
If the lockfile is partially updated but syntactically valid YAML, a subsequent pnpm install will attempt to reconcile node_modules to that lockfile. If the lockfile is truncated or references missing entries, install will error and manual repair is required.
There is no documented transactional upgrade mode or automatic lockfile rollback flag. --frozen-lockfile and --lockfile-only can detect drift or update the lockfile without touching node_modules, but they do not restore a prior lockfile state.
Lockfile persistence typically uses a temp file then rename. A crash or SIGKILL during the write window can leave a truncated or partially updated YAML file. Because the lockfile is written in place, there is no retained backup inside pnpm.
pnpmpnpm --version. Atomic write and error handling are version-sensitive.pnpm install --frozen-lockfile. A parse error means the file is corrupted.git diff pnpm-lock.yaml. Assess how partial the update is.pnpm install. Do not prune or delete ~/.pnpm-store; the store content remains valid and deletion only forces re-downloads.One missing diagnostic detail that changes the recommendation: the exact pnpm major version in use. Behavior around atomic writes and error recovery differs across releases.
Use comments to ask for clarification. Post a solution as an answer.
35,275 reputation · 27 Sept 2021, 20:37 UTC
The existing answer correctly notes that --frozen-lockfile prevents lockfile mutation. A useful distinction: --prefer-frozen-lockfile (the default in CI for many setups) allows pnpm to update the lockfile when resolution would otherwise fail, but it still won't roll back a partially written file from a prior interrupted upgrade. If you're debugging a corrupted lockfile, run pnpm install --frozen-lockfile first—it will fail fast on any mismatch rather than attempting reconciliation.
For version-specific behavior, test with a disposable project: start pnpm upgrade, send SIGKILL mid-write, then inspect pnpm-lock.yaml and run pnpm install --frozen-lockfile. This confirms whether your pnpm version uses atomic rename (most 8.x/9.x do) and how it surfaces parse errors versus resolution mismatches.