pnpm ERR_PNPM_OUTDATED_LOCKFILE — Fix Frozen Lockfile Failures

Diagnose pnpm frozen-lockfile failures by comparing package.json with pnpm-lock.yaml, aligning the pnpm version, and regenerating and committing the lockfile.

beginnerdebuggingpnpmlockfile

Symptoms

ERR_PNPM_OUTDATED_LOCKFILE Cannot install with frozen-lockfile because pnpm-lock.yaml is not up to date
Local install works but CI fails during pnpm install
The failure starts after merging a dependency change
pnpm reports the lockfile does not match package.json at the workspace root

Possible causes

package.json was edited but pnpm install was never run to update the lockfile
The lockfile was resolved with a different pnpm version or registry
A workspace package was added without including it in the lockfile importers
A merge kept one side's package.json and the other side's lockfile

Diagnosis steps

Reproduce the frozen install locally

pnpm install --frozen-lockfile

Interpretation

The error names the file that drifted. If it passes locally but fails in CI, compare the pnpm version and the committed lockfile revision.

Compare package.json with the lockfile

git diff -- package.json pnpm-lock.yaml && pnpm why react | head -30

Interpretation

A package.json change without a lockfile change is the direct cause. pnpm why shows how a dependency is currently resolved.

Check the package manager version

pnpm --version && node -p "require('./package.json').packageManager" 2>/dev/null

Interpretation

A lockfile generated by pnpm 9 read by pnpm 8 produces different resolution and frozen failures. Corepack should activate the version pinned in packageManager.

Inspect workspace importers

pnpm -r list --depth -1 | head -30 && grep -n 'importers:' pnpm-lock.yaml | head

Interpretation

A new workspace package missing from importers means the lockfile was not regenerated after adding it to pnpm-workspace.yaml.

Root cause

pnpm records the exact resolution of every dependency in pnpm-lock.yaml. Frozen installation treats that file as immutable: if package.json or the workspace layout requires a resolution the lockfile does not contain, pnpm aborts instead of rewriting it. Divergent pnpm versions and hand-merged lockfiles produce the same failure because the stored specifiers no longer match the manifests.

Fix

Run pnpm install with the project's pinned pnpm version, review the lockfile diff, and commit package.json and pnpm-lock.yaml together. Pin the toolchain with the packageManager field and Corepack so CI resolves with the same version. In a workspace, rerun install after adding or renaming a package so importers are regenerated. Never delete the lockfile to silence the check.

Risk note

Committing a lockfile generated by a different pnpm major changes many transitive resolutions at once. Deleting the lockfile loses reproducible builds and can introduce breaking patch updates. Updating dependencies while regenerating the lockfile makes the diff hard to review and hides the actual drift.

Verify the fix

Run pnpm install --frozen-lockfile in a fresh clone of the branch and confirm it completes without modifying the lockfile. Check git status is clean afterwards, then run the build and tests.

Frozen means “do not rewrite”

CI usually runs pnpm install --frozen-lockfile, which fails instead of updating the lockfile:

ERR_PNPM_OUTDATED_LOCKFILE  Cannot install with "frozen-lockfile"
because pnpm-lock.yaml is not up to date with package.json

That is the intended behavior. The lockfile is the contract for reproducible installs, so pnpm refuses to silently resolve something new.

Prove the drift

pnpm install --frozen-lockfile
git diff -- package.json pnpm-lock.yaml
pnpm --version
node -p "require('./package.json').packageManager"

If the lockfile diff is empty while package.json changed, the fix is to regenerate locally. If both changed but CI still fails, the pnpm version likely differs: a lockfile written by pnpm 9 may not satisfy pnpm 8.

Regenerate with the pinned toolchain

corepack enable
corepack prepare [email protected] --activate
pnpm install
git add package.json pnpm-lock.yaml

For workspaces, run install from the root after adding a package so all importers are recorded. If a merge produced an inconsistent lockfile, regenerate from the merged manifests rather than hand-editing YAML.

{
  "packageManager": "[email protected]"
}

Verify

Clone the branch into a clean directory and run pnpm install --frozen-lockfile. It must finish without changing the lockfile; git status should be clean afterwards. Then run the build and tests. If the command still fails, compare pnpm --version between the clean environment and CI before touching dependencies again.