pnpm ERR_PNPM_UNEXPECTED_VIRTUAL_STORE_DIR - Fix node_modules Drift in CI

pnpm records the virtual store path inside node_modules/.modules.yaml. If a cached node_modules was built against a different store location, pnpm refuses to reuse it and errors on the mismatch.

What this error means

pnpm install fails with ERR_PNPM_UNEXPECTED_VIRTUAL_STORE_DIR (or a modules-dir mismatch), because a restored node_modules cache points at a store path that does not match the current run’s store.

pnpm output

ERR_PNPM_UNEXPECTED_VIRTUAL_STORE_DIR  Unexpected virtual store location
Expected node_modules/.pnpm
Actual   /cache/.pnpm-store/v3/...
The node_modules was created for a different store directory.

Common causes

A cached node_modules built for a different store path

Restoring a node_modules cache whose .modules.yaml references a store dir different from the current pnpm config triggers the mismatch.

Store path changed between runs

A changed store-dir/--store-dir, a different cache location, or a different runner home moves the store, invalidating the cached node_modules.

How to fix it

Cache the store, not node_modules

Cache the content-addressable pnpm store and let pnpm reconstruct node_modules each run.

Terminal

# pin a stable store dir and cache that instead of node_modules
pnpm config set store-dir ~/.pnpm-store
rm -rf node_modules
pnpm install

Keep the store path stable

Set a consistent store-dir so it does not move between runs.
If a node_modules cache is stale, delete it and reinstall.
Key any store cache on pnpm-lock.yaml so it invalidates with dependency changes.

How to prevent it

Cache the pnpm store, not node_modules, in CI.
Pin a stable store-dir across runs.
Bust caches when the store path changes.