pnpm ERR_PNPM_LOCKFILE_BREAKING_CHANGE - Fix Incompatible Lockfile Format in CI

pnpm lockfiles carry a format version. ERR_PNPM_LOCKFILE_BREAKING_CHANGE means the committed pnpm-lock.yaml was written by a pnpm major whose lockfile format the pnpm running in CI cannot read.

What this error means

pnpm install (especially with --frozen-lockfile) fails with ERR_PNPM_LOCKFILE_BREAKING_CHANGE, indicating the lockfile format is incompatible with the installed pnpm. Local and CI pnpm versions disagree.

pnpm output

ERR_PNPM_LOCKFILE_BREAKING_CHANGE  Lockfile /app/pnpm-lock.yaml
not compatible with current pnpm
The lockfile was created with a newer version of pnpm.

Common causes

CI pnpm is older than the lockfile format

A teammate generated pnpm-lock.yaml with a newer pnpm major (newer lockfile format), but CI runs an older pnpm that cannot parse it.

pnpm version not pinned

Without pinning pnpm (via packageManager or setup), CI and local drift to different majors with incompatible lockfile formats.

How to fix it

Pin pnpm to match the lockfile

Use the same pnpm major everywhere via the packageManager field and Corepack.

package.json / Terminal

// package.json
"packageManager": "pnpm@9.7.0"

# in CI
corepack enable
corepack prepare pnpm@9.7.0 --activate
pnpm install --frozen-lockfile

Re-lock if you intend to upgrade

If you mean to move to a new pnpm major, upgrade pnpm everywhere first.
Regenerate pnpm-lock.yaml with the new pnpm and commit it.
Keep --frozen-lockfile in CI so drift fails loudly.

How to prevent it

Pin pnpm via packageManager and Corepack.
Upgrade pnpm in lockstep across local and CI.
Commit the lockfile and use --frozen-lockfile in CI.