pnpm 'ERR_PNPM_OUTDATED_LOCKFILE' after the agent edited package.json by hand

TL;DR

package.json changed without a lockfile refresh, so pnpm refuses to install. Run pnpm install, which updates pnpm-lock.yaml automatically, then review the lockfile diff and commit it. Never hand-edit the lockfile to match.

Error

pnpm 'ERR_PNPM_OUTDATED_LOCKFILE' after the agent edited package.json by hand

Steps

1. Confirm the drift: git diff package.json shows the hand edit; git status shows pnpm-lock.yaml unchanged. Expected output: You see the manifest change with no matching lockfile change.

2. Refresh the lockfile: pnpm install. Expected output: pnpm updates pnpm-lock.yaml and the outdated error is gone.

3. Review what moved: git diff pnpm-lock.yaml, checking that only the intended packages changed versions. Expected output: The diff matches the hand edit's intent.

4. Run the test suite to confirm the refreshed graph still works. Expected output: Tests pass on the new resolution.

5. Commit both files together so the next install is deterministic. Expected output: CI with a frozen lockfile goes green.

When to use

• pnpm fails with ERRPNPMOUTDATED_LOCKFILE after someone edited package.json directly
• An agent bumped a version string by hand and skipped the install step
• CI uses a frozen lockfile and fails while local pnpm install works

When not to use

• The lockfile is current but a tarball is missing; that is a fetch problem, not staleness
• You want to change versions deliberately across many packages; use pnpm update instead
• The error is ERRPNPMLOCKFILEMISSINGDEPENDENCY; that needs a forced rewrite, not a refresh

Variant phrasings

pnpm install fails with outdated lockfile in CI

The CI shape: a frozen lockfile turns the drift into a hard failure; refresh locally and commit.

Agent edited package.json and pnpm refuses to proceed

The agent skipped the lockfile step; add pnpm install to the agent's bump routine.

pnpm-lock.yaml out of sync after merging main

Merge conflicts resolved in package.json but not re-locked; pnpm install reconciles them.

Why it happens

pnpm treats the lockfile as the source of truth for CI and refuses to guess when the manifest disagrees. A hand edit to package.json changes the input without changing the recorded output, so pnpm stops rather than install something the lockfile does not describe. Running pnpm install re-resolves and records the new truth.

Edge cases

• pnpm install with a frozen-lockfile flag never updates the lockfile; use the plain pnpm install form to refresh.
• If the hand edit itself was wrong (a typo in the version), fix package.json first, then refresh.
• Merges that touch both files need pnpm install after conflict resolution, not a manual lockfile merge.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst42fSSqM1tyNV-13EK05ew