fs: fs.link() on exFAT volumes (Windows) fails with misleading EISDIR instead of "not supported"

[buddha68]

• Version: v24.19.0
• Platform: Windows 11 Home (10.0.22631), x64 — NTFS system drive; two USB exFAT volumes (4TB / 2TB)
• Subsystem: fs

What is wrong?

fs.linkSync(src, dest) targeting a file on an exFAT volume fails with errno EISDIR ("illegal operation on a directory"). The destination path does not exist and is not a directory. The real reason is that exFAT does not support hard links, and the underlying Win32 error is ERROR_INVALID_FUNCTION (WinError 1).

The EISDIR diagnosis actively misleads: it sends developers hunting for a directory that isn't there, instead of pointing at the unsupported filesystem operation.

Reproduction

On an exFAT-formatted volume (e.g. X:\):

$ node -e "require('fs').linkSync('X:\\a.tmp','X:\\b.tmp')"
Error: EISDIR: illegal operation on a directory, link 'X:\a.tmp' -> 'X:\b.tmp'

Python cross-check on the same volume shows the true underlying Win32 error:

$ python -c "import os; os.link(r'X:\a.tmp', r'X:\b.tmp')"
OSError: [WinError 1] 函数不正确。 (ERROR_INVALID_FUNCTION)

Observations from our test matrix (single machine, Windows 11 build 22631, Node v24.19.0):

Target volume	Filesystem	fs.linkSync result
C:, D:, F:	NTFS	succeeds
E: (USB), H: (USB)	exFAT	always fails with EISDIR

The failure splits perfectly along filesystem type, independent of internal/USB. Reads are unaffected; plain file writes work fine on exFAT.

Expected behavior

When CreateHardLinkW fails with ERROR_INVALID_FUNCTION on a filesystem without hard-link support, Node/libuv should surface a meaningful errno — e.g. ENOSYS ("function not implemented"), EPERM, or EOPNOTSUPP — rather than EISDIR.

For reference, on Linux, link(2) on filesystems that do not support hard links reports EPERM/EOPNOTSUPP, and on a system without the syscall at all ENOSYS.

Hypothesis (for upstream to confirm)

Possibly a missing mapping for ERROR_INVALID_FUNCTION in libuv's win32 uv_translate_sys_error, letting the failed uv_fs_link fall through to a misleading errno. We have not traced the exact layer; we only report the observed mapping WinError 1 (ERROR_INVALID_FUNCTION) → EISDIR.

Context / impact

This surfaced while diagnosing a third-party agent tool that publishes files via temp-file + hard-link: on exFAT drives every write failed, and the EISDIR message misattributed the cause. Reported downstream at deepseek-ai/deepseek-harness#5704 (includes the consumer-side analysis and a fallback-to-rename mitigation).

exFAT is the factory default format for many USB drives and SD cards, so "write to my external drive" is a common end-user scenario that hits this.

[Shivang9983]

Hi, @buddha68 I’d like to take this issue.

I’ve been able to reproduce the behavior and would like to trace the Windows error translation path from CreateHardLinkW through libuv to Node’s fs.link() implementation, specifically how ERROR_INVALID_FUNCTION ends up exposed as EISDIR.

I’ll verify the correct errno semantics, implement the mapping if the issue is in libuv, and add a regression test covering hard-link attempts on filesystems that do not support the operation.

Please assign this issue to me if it’s available. Thanks!

[buddha68]

@Shivang9983 Thanks for taking this on — much appreciated, and great to hear you've reproduced it.

For your tracing, our test data: the failure splits cleanly along filesystem type (internal NTFS C:/D:/F: all fine; two USB exFAT drives, 4TB and 2TB, always fail with EISDIR while the Win32 layer reports ERROR_INVALID_FUNCTION / WinError 1), on Windows 11 Home build 22631, Node v24.19.0. Happy to re-test any patch or candidate build on those two exFAT volumes if useful.

[Shivang9983]

Thanks for the detailed test information — that’s very helpful.
@buddha68

I’ll use the NTFS vs. exFAT behavior and the ERROR_INVALID_FUNCTION result as reference points while tracing the Windows error translation path through libuv/Node.js.
Once I have a candidate fix and regression test in place, I’ll share it for review. I may also reach out for a re-test on the two exFAT volumes to confirm the behavior is resolved end-to-end.

Thanks again for offering to test!

[MikeMcC399]

@Shivang9983

Please make sure you have read and understood the following documents:

• Guides and FAQs for first-time contributors
• Contribution and Automation Policies
• Pull Request Guide
• AI Use - Policy and Guidelines
• Code of Conduct

This includes advice that you should tackle only one issue at a time and that you should not open any new PRs until your first PR has been approved.

They also say;

Node.js is a community project driven by volunteers. There are no project managers to assign issues to people. There's no need to ask for assignments on GitHub. Instead, contributors usually use comments to communicate progress.

You have in parallel also requested to be assigned to another new issue #65816.

[Shivang9983]

Thank you @MikeMcC399
for the clarification. I apologize for misunderstanding the contribution process and for requesting assignment on multiple issues.

I’ve read through the contributor guidelines and understand that contributors should focus on one issue at a time and communicate progress through comments rather than requesting assignments.

I’ll focus exclusively on #65817 for now and won’t open another PR until my first PR has been approved.

I’ll also withdraw my request to take on #65816. Thanks for pointing this out.