pnpm error ERR_PNPM_OUTDATED_LOCKFILE after node version switch

pnpm error ERRPNPMOUTDATED_LOCKFILE after node version switch

TL;DR: Your lockfile was written by a different pnpm major version than the one now installed. Either switch back to the pinned pnpm via corepack, or regenerate the lockfile with pnpm install. The error is pnpm refusing to trust a lockfile format it does not understand - not a broken project.

pnpm error ERR_PNPM_OUTDATED_LOCKFILE after node version switch

Steps

1. Confirm the mismatch. Run pnpm --version and check the lockfileVersion line at the top of pnpm-lock.yaml. Expected: the installed pnpm major and the lockfile version belong to different pnpm majors (for example pnpm 10 installed but the lockfile says 9.0).

2. If the project pins pnpm in the packageManager field of package.json, run corepack enable and then re-run your install command. Corepack shims the pinned pnpm version automatically. Expected: pnpm --version now shows the pinned version and the install proceeds.

3. Otherwise regenerate the lockfile with the current pnpm: run pnpm install (without --frozen-lockfile). Expected: pnpm rewrites pnpm-lock.yaml and completes the install with no ERRPNPMOUTDATED_LOCKFILE.

4. Verify the tree is stable: run pnpm install --frozen-lockfile. Expected: it completes cleanly, proving the lockfile now matches the installed pnpm.

5. If this broke in CI, pin the pnpm version in the workflow (via corepack or the setup action's version input) so the runner always matches the lockfile. Expected: CI installs succeed on every run, not just on your machine.

Use this when

• pnpm install fails with ERRPNPMOUTDATED_LOCKFILE right after nvm use, a Node upgrade, or a corepack change.
• The lockfileVersion in pnpm-lock.yaml does not match the installed pnpm major.
• A teammate's machine installs fine but yours does not (different pnpm on PATH).

Not for this skill when

• The error comes from npm or yarn - different package managers, different lockfile errors.
• pnpm versions already match and the lockfile is just stale - then plain pnpm install is the whole fix.
• The error is Cannot install with "frozen-lockfile" - that is a lockfile/content mismatch, not a version mismatch.

Variant phrasings

• pnpm install fails with outdated lockfile after nvm use
• pnpm lockfileVersion mismatch between pnpm 9 and pnpm 10
• ERRPNPMOUTDATED_LOCKFILE when switching node versions

Why it happens

pnpm bumps its lockfile format between major versions. Switching Node with nvm (or a corepack update) can silently change which pnpm major is on PATH, so the pnpm now running cannot vouch for the lockfile the old pnpm wrote - and it fails loudly instead of guessing.

Edge cases

• Regenerating the lockfile can shift transitive dependency versions - review the pnpm-lock.yaml diff before committing.
• Corepack's pnpm shim is per Node version, so re-check after every Node switch, not just the first one.
• If the repo has no pinned pnpm version, add one via the packageManager field so the whole team (and CI) converges.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstnc-uHCnPrvVbPaovGYBGQ