ERR_PNPM_OUTDATED_LOCKFILE in CI: pre-commit enforcement vs deploy-time failure tradeoffs

The direct answer

Yes — a pnpm install --lockfile-only check followed by git diff --exit-code pnpm-lock.yaml detects the same manifest-vs-lockfile drift that --frozen-lockfile rejects in CI, because both paths compare package.json specifiers against the importers recorded in pnpm-lock.yaml. And you do not need a duplicated install stage: keep --frozen-lockfile as your single install step, but run it in the earliest CI job (build/test), not the deploy job. Drift then fails the pipeline in the first minute instead of at deploy time.

What is confirmed vs. inferred

Confirmed by the error itself: ERR_PNPM_OUTDATED_LOCKFILE names the mismatching specifiers, so the CI log already tells you exactly which dependency entries drifted. The rest is version-sensitive: --frozen-lockfile defaults, lockfile format versions, and error behavior changed across pnpm 7/8/9. Since your project pins pnpm via the packageManager field, verify the following against that pinned version rather than assuming parity.

The recommended pattern

1. Local gate (pre-commit or pre-push): run the lockfile-only check only when package.json or pnpm-lock.yaml is staged:

pnpm install --lockfile-only
git diff --exit-code pnpm-lock.yaml

If the diff is non-empty, the hook fails and the developer must deliberately regenerate and commit the lockfile. Critically, the hook must fail on diff, not auto-stage the regenerated file — --lockfile-only rewrites the lockfile rather than merely validating it, and auto-committing can silently pull newer transitive versions within semver ranges into a PR without review.

1. CI gate: no new stage. Move the existing pnpm install --frozen-lockfile to the first job. If you want an even cheaper early signal, pnpm install --frozen-lockfile --lockfile-only validates consistency without linking node_modules, costing seconds — but the full install in the build job is still the authoritative check.
2. Version alignment: ensure local and CI run the same pnpm major via Corepack and the packageManager field. Note that Corepack's availability in the Node.js ecosystem has been in flux, so confirm how your CI image actually provides the pinned pnpm.

Tradeoffs

The pre-commit hook catches drift before it ever reaches a branch, at the cost of a few seconds on relevant commits. The CI-first-job placement is the safety net for anything that bypasses hooks. Deploy-time failure alone is the worst option: it wastes the entire pipeline run and blocks releases for a purely local mistake.

What neither gate catches

A fresh, consistent lockfile does not guarantee a working deployment. Phantom dependencies — imports of packages you never declared, which resolve only through hoisting artifacts — surface at runtime, not install time. Lockfile freshness is necessary but not sufficient.

Verification

• Edit a dependency version in package.json without updating the lockfile; run the hook and confirm it exits nonzero.
• Push the drifted state and confirm the first CI job fails with ERR_PNPM_OUTDATED_LOCKFILE before any build or deploy work.
• Compare pnpm --version locally and in CI before trusting behavioral parity.