fix: fall back to copy when hard links fail in pnpm linker by VforVitality · Pull Request #7067 · yarnpkg/berry

VforVitality · 2026-03-11T12:23:04Z

Summary

When using
odeLinker: pnpm, the content-addressable index creates hard links from the global index to
ode_modules/.store/. This fails in several common scenarios:

Error code	Cause
EXDEV	Index and project on different volumes (Docker, CI, Windows multi-drive)
EMLINK	Inode hard link limit exceeded (Linux/macOS)
UNKNOWN (link syscall)	NTFS hard link limit of 1024 per file (Windows) — libuv doesn't map \ERROR_TOO_MANY_LINKS\ to EMLINK
EPERM (link syscall)	Insufficient privileges for hard links (Windows without Developer Mode)

This PR adds graceful degradation: when \linkPromise\ fails with any of these errors, the file content is copied from the index instead. This matches the behavior of the real pnpm CLI, which also falls back to copying.

Changes

**\packages/yarnpkg-fslib/sources/algorithms/copyPromise.ts**: Added \shouldFallbackToCopy()\ helper and wrapped the \linkPromise\ call in \copyFileViaIndex()\ with try/catch + copy fallback
**\packages/yarnpkg-fslib/tests/copyPromise.test.ts**: Added comprehensive unit tests covering EXDEV, EMLINK, UNKNOWN+link, EPERM+link fallback, plus negative tests (UNKNOWN without link syscall, EACCES propagation)

Testing

Unit tests

All 8 test suites pass (104 passed, 5 platform-skipped):
\
yarn test:unit yarnpkg-fslib # ✅ 8 passed, 0 failed
\\

Real-world validation

Tested against a large monorepo (~40 workspaces) with @mui/icons-material\ (~17,000 .d.ts\ files with identical content hashing to the same index entry):

Before fix: \UNKNOWN: unknown error, link\ (errno -4094) — Yarn crashes at ~1024 hard links
After fix: Install completes successfully. Files at the NTFS limit are hard-linked (1023 links), overflow files are transparently copied

Fixes #5326

tobiasweibel · 2026-03-26T13:39:47Z

packages/yarnpkg-fslib/sources/algorithms/copyPromise.ts

+        if (shouldFallbackToCopy(err)) {
+          const content = await destinationFs.readFilePromise(indexPath);
+          await destinationFs.writeFilePromise(destination, content);
+          if (sourceMode !== defaultMode)


Missing curly bracket

Suggested change

if (sourceMode !== defaultMode)

if (sourceMode !== defaultMode) {

tobiasweibel · 2026-03-26T13:51:30Z

packages/yarnpkg-fslib/tests/copyPromise.test.ts

+import {NodeFS}                                    from '../sources/NodeFS';
+import {xfs, PortablePath, ppath, Filename, npath} from '../sources';


Linter fix

Suggested change

import {NodeFS} from '../sources/NodeFS';

import {xfs, PortablePath, ppath, Filename, npath} from '../sources';

import {NodeFS} from '../sources/NodeFS';

import {xfs, ppath, Filename} from '../sources';

tobiasweibel · 2026-03-26T13:53:46Z

@VforVitality it would be nice to get this done. It would probably fix an issue I see when hard linking files from outside of a docker into the image.

VforVitality · 2026-03-29T19:40:52Z

Hi @tobiasweibel
Thank you for help and review, I'm sorry for being so slow :D

The thing is that we started using a 'same-way-patched' yarn (4.7.0 in our case) and even though it works with the fallback, we experienced some performance degradation on ntfs.

So I went deeper with my research and turned out that try to link, then catch is slow. So I tried to implement threshold, and not even try to link beyond that threshold. Seems to be working for now (plan to test it this week).

I'm only not sure if this improvement should be a part of this PR? Anyone, any opinion? Shall it just fix the issue or also to try to improve performance a bit?

When using nodeLinker: pnpm, the content-addressable index creates hard links from the index to node_modules/.store/. This fails in several scenarios: - EXDEV: index and project on different volumes (common in Docker, CI, and Windows multi-drive setups) - EMLINK: inode hard link limit exceeded (Linux/macOS) - UNKNOWN (link syscall): NTFS hard link limit of 1024 per file (Windows); libuv does not map ERROR_TOO_MANY_LINKS to EMLINK - EPERM (link syscall): insufficient privileges for hard links This commit adds a shouldFallbackToCopy() helper that detects these errors, and wraps the linkPromise call in copyFileViaIndex() with a try/catch that gracefully degrades to copying the file content. This matches the behavior of the real pnpm CLI. Fixes yarnpkg#5326

packages/yarnpkg-fslib/tests/copyPromise.test.ts

Co-authored-by: Tobias Weibel <tobias.weibel@autodesk.com>

arcanis · 2026-03-30T14:10:45Z

So I went deeper with my research and turned out that try to link, then catch is slow. So I tried to implement threshold, and not even try to link beyond that threshold. Seems to be working for now (plan to test it this week).

Rather than a threshold, perhaps we could just feature-detect it before starting the link itself?

clemyan · 2026-03-31T16:47:13Z

I don't like that this happens silently. Copying instead of hardlinking defeats one of the main benefits of the pnpm linker.

I think this should be at least gated behind a configuration

VforVitality · 2026-04-02T08:59:06Z

I don't like that this happens silently. Copying instead of hardlinking defeats one of the main benefits of the pnpm linker.

I think this should be at least gated behind a configuration

What would be default behavior then? When configuration is not provided, shall yarn install just fail?
Anyway we fallback to copy only for very specific files, which cannot be linked due to file system limitations.

So I went deeper with my research and turned out that try to link, then catch is slow. So I tried to implement threshold, and not even try to link beyond that threshold. Seems to be working for now (plan to test it this week).

Rather than a threshold, perhaps we could just feature-detect it before starting the link itself?

I haven't found a better solution. Threshold is also not that good, it tries to predict the future and there are no guarantee.
So the current approach: try to link, catch, copy as fallback is ok, imho.

clemyan · 2026-04-04T06:23:26Z

What would be default behavior then? When configuration is not provided, shall yarn install just fail?

Yes. That's the existing behavior. Maybe with an added note about the config in the error message.

Anyway we fallback to copy only for very specific files, which cannot be linked due to file system limitations.

"Very specific files" here includes "all files on a different drive from the global CAS".

Imagine a user switching to the pnpm linker because it "saves disk space", then finding out 10 projects later that it saved no space at all because they put all their projects on a different drive.

VforVitality · 2026-04-14T06:52:50Z

What would be default behavior then? When configuration is not provided, shall yarn install just fail?

Yes. That's the existing behavior. Maybe with an added note about the config in the error message.

I cannot agree. Current behavior is a bug. We try to fix it. Why shall we behave as bug?

Anyway we fallback to copy only for very specific files, which cannot be linked due to file system limitations.

"Very specific files" here includes "all files on a different drive from the global CAS".

Imagine a user switching to the pnpm linker because it "saves disk space", then finding out 10 projects later that it saved no space at all because they put all their projects on a different drive.

Well, this might be the case. At maximum, I think we could put a message to the console. Shall we?
Anyway pnpm's approach doesn't work well on windows, the main beneficiaries are linux users and CI. pnpm does the same: copy if cannot link.

Btw in our case, how we landed down here: we wanted to use pnpm linked to detect phantom deps (not to save space). Because of cross-device links issue, we just disabled yarn's global cache. It's not obvious, but works well :)

tobiasweibel reviewed Mar 26, 2026

View reviewed changes

VforVitality force-pushed the fix/5326-pnpm-linker-hardlink-fallback branch from bd34268 to 98ae0a7 Compare March 29, 2026 19:29

VforVitality force-pushed the fix/5326-pnpm-linker-hardlink-fallback branch from 98ae0a7 to e311aff Compare March 29, 2026 19:44

tobiasweibel reviewed Mar 30, 2026

View reviewed changes

packages/yarnpkg-fslib/tests/copyPromise.test.ts Outdated Show resolved Hide resolved

Update packages/yarnpkg-fslib/tests/copyPromise.test.ts

a7d4d0a

Co-authored-by: Tobias Weibel <tobias.weibel@autodesk.com>

release strategy

72f0c56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: fall back to copy when hard links fail in pnpm linker#7067

fix: fall back to copy when hard links fail in pnpm linker#7067
VforVitality wants to merge 3 commits intoyarnpkg:masterfrom
VforVitality:fix/5326-pnpm-linker-hardlink-fallback

VforVitality commented Mar 11, 2026

Uh oh!

tobiasweibel Mar 26, 2026

Uh oh!

tobiasweibel Mar 26, 2026

Uh oh!

tobiasweibel commented Mar 26, 2026

Uh oh!

VforVitality commented Mar 29, 2026

Uh oh!

Uh oh!

arcanis commented Mar 30, 2026

Uh oh!

clemyan commented Mar 31, 2026

Uh oh!

VforVitality commented Apr 2, 2026

Uh oh!

clemyan commented Apr 4, 2026

Uh oh!

VforVitality commented Apr 14, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

	if (sourceMode !== defaultMode)
	if (sourceMode !== defaultMode) {

		import {NodeFS} from '../sources/NodeFS';
		import {xfs, PortablePath, ppath, Filename, npath} from '../sources';

Uh oh!

Conversation

VforVitality commented Mar 11, 2026

Summary

Changes

Testing

Unit tests

Real-world validation

Uh oh!

tobiasweibel Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

tobiasweibel Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

tobiasweibel commented Mar 26, 2026

Uh oh!

VforVitality commented Mar 29, 2026

Uh oh!

Uh oh!

arcanis commented Mar 30, 2026

Uh oh!

clemyan commented Mar 31, 2026

Uh oh!

VforVitality commented Apr 2, 2026

Uh oh!

clemyan commented Apr 4, 2026

Uh oh!

VforVitality commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

VforVitality commented Apr 14, 2026 •

edited

Loading