[Bug]: Windows - missing files at install on large packages

[ClementValot]

Self-service

• I'd be willing to implement a fix

Describe the bug

When installing a large package (e.g. @mui/icons-material, which has 10k+ flat files) , on Windows, with nodeLinker: node_modules and nmMode: hardlinks-global, some files may be missing in the final node_modules.

This appears to be linked to the Windows file-system failing silently on bulk symlinking

To reproduce

Below are redacted package.json, yarnrc, yarn.lock, and a checksums file I was advised to provide :)

yarn.lock.copy.txt

.yarnrc.yml

package.json

checksums.txt

After install, the @mui/icons-material has some missing files. Namely, all the .js and .mjs files seem to be present, but only the first 1024 .d.mts files, and none of the d.ts files are present, which seems to indicate that the symlinking happens by batches of 1024 files, grouped by file extension.

Environment

System:
    OS: Windows 11 10.0.26200
    CPU: (12) x64 Snapdragon(R) X Elite - X1E80100 - Qualcomm(R) Oryon(TM) CPU
  Binaries:
    Node: 24.16.0 
    Yarn: 4.17.0 
    npm: 11.13.0

Additional context

• The files in the cache are correct, clearing the cache, fresh installs, and deleting yarn.lock don't change the behavior which seems to be deterministic in my setup

• I'll try and gather some logs

[NormalGaussian]

I think it is because it's hard links:

"The maximum number of hard links that can be created with this function is 1023 per file. If more than 1023 links are created for a file, an error results." https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-createhardlinka

When looking at the checksums there are an awful lot of 0e02a00a5d1f3f3ef8d4e731c9f74ef6 {myProject}\node_modules@mui\icons-material*.d.mts

Same checksum, same file, probably hitting the limit and yarn/node is not propagating it.

I'm on my phone so can't easily count the hashes/duplicates of missing files to confirm.

[NormalGaussian]

I don't have a windows machine to duplicate on exactly; but cloning onto linux and comparing the checksum files shows the following:

• only @mui/icons-material is affected in the example; its *.d.ts files for icons are identical in content
• only @mui/icons-material has such a large number of identical files (21.5k)
• other packages with similar file counts are typically occurring due to localisation, but some are shared across packages as well. breakdown (6.9 MB)

As link count is a system-wide limit per-file, this will cause an issue for other packages if they are installed with hardlinks across multiple packages; having only 6 different hardlinks projects that use date-fns as a dependency would trigger this.

---

I think the error originates here

berry/packages/plugin-nm/sources/NodeModulesLinker.ts

Lines 782 to 786 in 352c4d6

	await xfs.linkPromise(contentFilePath, dstPath);
	doesContentFileExist = true;
	} catch {
	doesContentFileExist = false;
	}

where the error is swallowed.

Ideally all fatal errors would be raised and not ignored.

Ideally EMLINK error could be handled - I'm thinking by adding an index number to the end of the source file, and creating/incrementing until one is found that doesn't cause an EMLINK error. Naively implemented this could be slow - one icons-material would need ~21 files which means ~10x the number of write attempts for that package.

---

@ClementValot - an immediate mitigation for you might be to re-vendor the mui/icons-material package but to use a script to inject the icon name into all of the .d.ts files therefore making them have a different hash.

[ClementValot]

Oooh I get it, because a large number of files (1024+, namely) have the exact same content, they've all got the same checksum, and when writing the node_modules all the files are symlinked to the same source file in the store, hence the windows error because of the limitation mentioned above.

Honestly there's room for optimization in the mui package itself, I'll open up a PR back there, I've got a couple ideas worth discussing.

On the other hand this unexpected error should have been caught by yarn, so either a workaround or an error message has to be implemented, and this is a tad bit above my skillset

[NormalGaussian]

On raising this issue elsewhere, bear in mind that packages like mui/icons-material often layout like they do so that unused files aren't pulled in by bundlers.

[ClementValot]

Windows file-system bindings are a bit above my paygrade, but tree-shaking is right up my alley :)