pnpm "ERR_PNPM_LINKING_FAILED" in CI

pnpm installs by linking packages from its content-addressable store into node_modules. The link operation failed - usually because the store and node_modules are on different filesystems, or permissions blocked it.

What this error means

Install fails with ERR_PNPM_LINKING_FAILED, sometimes citing EXDEV (cross-device link) or EACCES. It tends to appear on containerized runners where the store and workspace sit on different mounts.

ERR_PNPM_LINKING_FAILED  Error: EXDEV: cross-device link not permitted,
link '/pnpm-store/v3/...' -> '/work/repo/node_modules/.pnpm/...'

Common causes

Store and node_modules on different filesystems

Hard links cannot cross devices (EXDEV). A store on one mount and a workspace on another breaks pnpm linking.

Permissions on the store or workspace

A store directory owned by a different user, or a read-only mount, blocks the link.

How to fix it

Put the store on the same filesystem

Set the pnpm store directory under the workspace mount so links stay on one device.

pnpm config set store-dir /work/repo/.pnpm-store
pnpm install --frozen-lockfile

Fall back to copying when linking is impossible

If the store must live elsewhere, tell pnpm to copy instead of hard-link.

pnpm install --package-import-method copy

How to prevent it

• Keep the pnpm store on the same filesystem as node_modules.
• Ensure the store directory is writable by the CI user.
• Latchkey self-healing managed runners auto-retry transient linking/extraction failures and provide a persistent same-filesystem cache so the pnpm store links cleanly.

Related guides