# pnpm error ERR_PNPM_OUTDATED_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.

```text
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 ERR_PNPM_OUTDATED_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 ERR_PNPM_OUTDATED_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
- ERR_PNPM_OUTDATED_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/pst_nc-uHCnPrvVbP_aovGYBGQ