pnpm ERR_PNPM_LINKING_FAILED - Fix Store-to-node_modules Link Errors in CI

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.