# \`zig fetch\` failed if target project contains symlink

**URL:** <https://ziggit.dev/t/zig-fetch-failed-if-target-project-contains-symlink/16275>\
**Category:** Help\
**Tags:** c, build-system\
**Created:** [June 21, 2026, 6:26am UTC](https://ziggit.dev/t/zig-fetch-failed-if-target-project-contains-symlink/16275 "2026-06-21T06:26:51Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![Verafahn](https://ziggit.dev/user_avatar/ziggit.dev/verafahn/32/9285_2.png) [@Verafahn](https://ziggit.dev/u/Verafahn)\
**Post date:** [June 21, 2026, 6:26am UTC](https://ziggit.dev/t/zig-fetch-failed-if-target-project-contains-symlink/16275/1 "2026-06-21T06:26:51Z")

</div>

Zig version: 0.16.0 (On Windows)

Expectation: Zig should be able to handle any type of file in the repository.

## Bug Report

If a project contains symbolic links (symlinks), it cannot be successfully fetched by the `zig fetch` command.

[Here](https://github.com/Verafahn/bug-report) is a minimal example: a project that includes a symlink pointing to the `README` file. When you attempt to fetch it with `zig fetch`, the following error occurs:

```zig
error: unable to hash 'README': Unexpected

```

This issue may prove fatal to compatibility with the C/C++ ecosystem.

🤔

`lib/std.Io.zig`

```zig
pub const UnexpectedError = error{
    /// The Operating System returned an undocumented error code.
    ///
    /// This error is in theory not possible, but it would be better
    /// to handle this error than to invoke undefined behavior.
    ///
    /// When this error code is observed, it usually means the Zig Standard
    /// Library needs a small patch to add the error code to the error set for
    /// the respective function.
    Unexpected,
};

```

---

<div class="post-metadata">

**Author:** ![Verafahn](https://ziggit.dev/user_avatar/ziggit.dev/verafahn/32/9285_2.png) [@Verafahn](https://ziggit.dev/u/Verafahn)\
**Post date:** [June 21, 2026, 9:42am UTC](https://ziggit.dev/t/zig-fetch-failed-if-target-project-contains-symlink/16275/2 "2026-06-21T09:42:29Z")

</div>

```zig
error.Unexpected NTSTATUS=0x103 (PENDING)
E:/_dev/zig/build/stage3/lib/zig/std/Io/Threaded.zig:1459:40: 0x7ff60f29b409 in unexpectedNtstatus (zig_zcu.obj)
        return windows.unexpectedStatus(status);
                                       ^
E:/_dev/zig/build/stage3/lib/zig/std/Io/Threaded.zig:8202:59: 0x7ff60f2ff021 in dirReadLinkWindows (zig_zcu.obj)
        else => |status| return syscall.unexpectedNtstatus(status),
                                                          ^
E:/_dev/zig/build/stage3/lib/zig/std/Io/Threaded.zig:8079:46: 0x7ff60f2fc9a4 in dirReadLink (zig_zcu.obj)
        .windows => return dirReadLinkWindows(dir, sub_path, buffer),
                                             ^
E:/_dev/zig/build/stage3/lib/zig/std/Io/Dir.zig:1303:33: 0x7ff60f713e40 in readLink (zig_zcu.obj)
    return io.vtable.dirReadLink(io.userdata, dir, sub_path, buffer);
                                ^
E:\_dev\zig\src\Package\Fetch.zig:1922:54: 0x7ff60f729a60 in hashFileFallible (zig_zcu.obj)
            const link_name = buf[0..try dir.readLink(io, hashed_file.fs_path, &buf)];
                                                     ^
E:\_dev\zig\src\Package\Fetch.zig:1890:43: 0x7ff60f729699 in workerHashFile (zig_zcu.obj)
    hashed_file.failure = hashFileFallible(io, dir, hashed_file);
                                          ^
E:/_dev/zig/build/stage3/lib/zig/std/Io.zig:1265:17: 0x7ff60f72955b in start (zig_zcu.obj)
                _ = @as(Cancelable!void, @call(.auto, function, args_casted.*)) catch {};
                ^
E:/_dev/zig/build/stage3/lib/zig/std/Io/Threaded.zig:553:22: 0x7ff60f312427 in start (zig_zcu.obj)
            task.func(task.contextPointer());
                     ^
E:/_dev/zig/build/stage3/lib/zig/std/Io/Threaded.zig:1798:29: 0x7ff60f31167f in worker (zig_zcu.obj)
            runnable.startFn(runnable, &thread, t);
                            ^
E:/_dev/zig/build/stage3/lib/zig/std/Thread.zig:422:13: 0x7ff60f3111b1 in callFn__anon_48619 (zig_zcu.obj)
            @call(.auto, f, args);
            ^
E:/_dev/zig/build/stage3/lib/zig/std/Thread.zig:536:30: 0x7ff60f31108a in entryFn (zig_zcu.obj)
                return callFn(f, self.fn_args);
                             ^
???:?:?: 0x7ffaabd5e956 in ??? (KERNEL32.DLL)
???:?:?: 0x7ffaad267c1b in ??? (ntdll.dll)
error: unable to hash 'README': Unexpected

```

`lib/zig/std/Io/Threaded.zig`

```zig
// Line: 8179
    syscall = try .start();
    while (true) switch (windows.ntdll.NtFsControlFile(
        result_handle,
        null, // event
        null, // APC routine
        null, // APC context
        &io_status_block,
        .GET_REPARSE_POINT,
        null, // input buffer
        0, // input buffer length
        &reparse_buf,
        reparse_buf.len,
    )) {
        .SUCCESS => {
            syscall.finish();
            break;
        },
        .CANCELLED => {
            try syscall.checkCancel();
            continue;
        },
        .NOT_A_REPARSE_POINT => return syscall.fail(error.NotLink),
        else => |status| return syscall.unexpectedNtstatus(status),
    };
// Line: 8204

```

and [NtFsControlFile function (ntifs.h) - Windows drivers | Microsoft Learn](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntfscontrolfile#return-value)

---

<div class="post-metadata">

**Author:** ![castholm](https://ziggit.dev/user_avatar/ziggit.dev/castholm/32/1330_2.png) [@castholm](https://ziggit.dev/u/castholm)\
**Post date:** [June 21, 2026, 10:10am UTC](https://ziggit.dev/t/zig-fetch-failed-if-target-project-contains-symlink/16275/3 "2026-06-21T10:10:20Z")

</div>

This is a known issue and the current proposed fix is to introduce a `.symlink_behavior = (.keep|.omit|.copy)` option to `build.zig.zon` that would let you specify how to handle symlinks when unpacking dependencies.

> <https://github.com/ziglang/zig/issues/17652>
>
> \### Zig Version
> 
> zig-windows-x86\_64-0.12.0-dev.983+78f2ae7f2
> 
> \### Steps to Repro…duce and Observed Behavior
> 
> Download my project on windows:
> https://github.com/PixelGuys/Cubyz/tree/0c2d309f2af7e66fdb99bb5dac2a2237635151aa
> (Sorry for just dumping the entire project here. I don't own windows, so sadly I couldn't create a minimal reproducible. So I only have a report from a user who stumbled over the error)
> Run it with \`zig build run\` or \`run.bat\`(this one automatically downloads the right zig version)
> Observe the following error:
> \`\`\`
> error: unable to unpack tarball
> .url = "https://github.com/harfbuzz/harfbuzz/archive/refs/tags/8.2.2.tar.gz",
> note: unable to create symlink from 'README' to 'README.md': AccessDenied
> \`\`\`
> 
> \### Expected Behavior
> 
> Zig should support packages that contain symlinks. It works fine on Linux by the way.
> 
> If it is impossible to create symlinks on windows without permissions, then zig should at least use a workaround, like replacing the symlink file with a copy of the original or something like that.

> <https://github.com/ziglang/zig/issues/22350>
>
> This is a proposal to address the use case described in #17652.
> 
> The idea here… is to add a new field to build.zig.zon when fetching a tarball that describes a symlink strategy when unpacking:
> 
> \`\`\`zig
> .dependencies = .{
> .libz = .{
> .url = "https://github.com/allyourcodebase/zlib/archive/refs/tags/1.3.1-3.tar.gz",
> .hash = "1220138f4aba0c01e66b68ed9e1e1e74614c06e4743d88bc58af4f1c3dd0aae5fea7",
> .symlink\_behavior = .keep,
> },
> \`\`\`
> 
> The enum:
> 
> \`\`\`zig
> /// Describes how to handle all symlinks when unpacking, before hash computation.
> pub const SymlinkBehavior = enum {
> /// (default) create symlinks when unpacking
> keep,
> /// skip creation of all symlinks when unpacking
> omit,
> /// make copies of all files that would be symlinked. Uses hard linking when possible as an optimization.
> copy,
> };
> \`\`\`

Edit: Although the linked issues only concern fetching what is already declared in `build.zig.zon`, not the `zig fetch` command itself. But I would expect that the proposed fix also implies fixing the `zig fetch` command.

---

<div class="post-metadata">

**Author:** ![Verafahn](https://ziggit.dev/user_avatar/ziggit.dev/verafahn/32/9285_2.png) [@Verafahn](https://ziggit.dev/u/Verafahn)\
**Post date:** [June 21, 2026, 10:20am UTC](https://ziggit.dev/t/zig-fetch-failed-if-target-project-contains-symlink/16275/4 "2026-06-21T10:20:18Z")

</div>

> [@castholm](#):
>
> This is a known issue and the current proposed fix is to introduce a `.symlink_behavior = (.keep|.omit|.copy)` option to `build.zig.zon` that would let you specify how to handle symlinks when unpacking dependencies.

I think it should be indicated in the error message of command `zig fetch`.

But I see that #22350 is marked as urgent and has not been closed yet. Does it support it in the current Zig version?

---

<div class="post-metadata">

**Author:** ![castholm](https://ziggit.dev/user_avatar/ziggit.dev/castholm/32/1330_2.png) [@castholm](https://ziggit.dev/u/castholm)\
**Post date:** [June 21, 2026, 10:52am UTC](https://ziggit.dev/t/zig-fetch-failed-if-target-project-contains-symlink/16275/5 "2026-06-21T10:52:49Z")

</div>

No, it hasn’t been implemented yet. The “urgent” milestone means that the issue is in the backlog and should be worked on when given time, but that it’s not blocking a tagged release and less prioritized than issues tagged as 0.17, 0.18, etc.

* * *

However, I see now that the status code you got was `PENDING` which normally shouldn’t occur, so this might be a bug in the package fetching implementation on Windows. `error.Unexpected` should never be surfaced to users when using I/O APIs correctly, so you might want to consider filing a bug report stating that the expected behavior is to return an error that clearly communicates that symlinks are unsupported.

---

<div class="post-metadata">

**Author:** ![tholmes](https://ziggit.dev/user_avatar/ziggit.dev/tholmes/32/5641_2.png) [@tholmes](https://ziggit.dev/u/tholmes)\
**Post date:** [June 21, 2026, 11:35am UTC](https://ziggit.dev/t/zig-fetch-failed-if-target-project-contains-symlink/16275/6 "2026-06-21T11:35:16Z")

</div>

Yeah, in pre-0.16.0 versions it’d give you error.AccessDenied. Which isn’t actually much more descriptive on Windows…

---

<div class="post-metadata">

**Author:** ![squeek502](https://ziggit.dev/user_avatar/ziggit.dev/squeek502/32/409_2.png) [@squeek502](https://ziggit.dev/u/squeek502)\
**Post date:** [June 22, 2026, 6:00am UTC](https://ziggit.dev/t/zig-fetch-failed-if-target-project-contains-symlink/16275/7 "2026-06-22T06:00:06Z")

</div>

> [@castholm](#):
>
> However, I see now that the status code you got was `PENDING`

It’s also failing during `dirReadLink`, so it’s not failing to create the symlink in this case.
