pnpm ERR_PNPM_LINKING_FAILED - Fix Store-to-node_modules Link Errors in CI
By Kaveh Alemi·Latchkey
pnpm installs by hard-linking (or reflinking) packages from its content-addressable store into node_modules. ERR_PNPM_LINKING_FAILED means that link could not be created - most often because the store and the project live on different filesystems.
What this error means
pnpm install fails with ERR_PNPM_LINKING_FAILED, often citing a cross-device link error (EXDEV) or a permission problem. Common in Docker when the pnpm store is on one mount/volume and the project on another.
pnpm output
ERR_PNPM_LINKING_FAILED Error: EXDEV: cross-device link not permitted,
link '/pnpm-store/v3/files/...' -> '/app/node_modules/.pnpm/...'
Common causes
Store and project on different filesystems
Hard links cannot cross filesystem boundaries (EXDEV). If the pnpm store is on a different mount/volume than node_modules, linking fails.
Permission or read-only target
A read-only mount or a node_modules owned by another user prevents pnpm from creating the links.
How to fix it
Put the store on the same filesystem
Set the pnpm store to a path on the same volume as the project, or switch the link mode.
Terminal
# keep store on the same filesystem as node_modules
pnpm config set store-dir /app/.pnpm-store
# or copy instead of hard-link if they must differ
pnpm install --config.package-import-method=copy
Fix permissions and mounts
Ensure node_modules and the store are writable by the build user.
Avoid read-only mounts for the install target.
Place the store and project on one mount to keep hard-linking fast.
How to prevent it
Keep the pnpm store on the same filesystem as the project.
Use the copy import method when stores must be separate.
Install on writable, single-volume layers in Docker.
Frequently asked questions
What causes ""ERR_PNPM_LINKING_FAILED""?
Hard links cannot cross filesystem boundaries (EXDEV). If the pnpm store is on a different mount/volume than node_modules, linking fails.
How do I fix "ERR_PNPM_LINKING_FAILED"?
Set the pnpm store to a path on the same volume as the project, or switch the link mode.
Can Latchkey fix this automatically?
Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.
