# A caching problem with 0.17

**URL:** <https://ziggit.dev/t/a-caching-problem-with-0-17/17929>\
**Category:** Help\
**Tags:** build-system, llm, zig-0-17\
**Created:** [October 12, 2026, 8:00pm UTC](https://ziggit.dev/t/a-caching-problem-with-0-17/17929 "2026-10-12T20:00:55Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![Ippokratis](https://ziggit.dev/letter_avatar_proxy/v4/letter/i/9e8a1a/32.png) [@Ippokratis](https://ziggit.dev/u/Ippokratis)\
**Post date:** [October 12, 2026, 8:00pm UTC](https://ziggit.dev/t/a-caching-problem-with-0-17/17929/1 "2026-10-12T20:00:55Z")

</div>

Hi,  
I use zig to build a c++ JUCE project on a Mac M2 Silicon running Tahoe 26.6.2 and recently updated to Zig 0.17.  
Today I had the following problem: I build the project but the executable didn’t get updated. After some research, Claude claimed that the problem lies in Zig.  
I am not so proficient in Zig to judge for myself if the problem was indeed in Zig and I cannot send a bug report due to the no AI bug report policy, which is fine.  
Because I benefit greatly from using Zig daily, I still wanted to provide some feedback, so I chose this forum. I asked for a minimal project that can recreate the problem, it is here. The problem was real, I am unsure about the cause.

Kind regards.

# Zig 0.17.0: a header change is missed after a link-only rebuild

## The problem

Zig keeps two kinds of cache notes for a C program:

1. **A note for each source file.** It lists the source and every header the compiler read while compiling it, for example `main.c` and `value.h`. This note is correct.
2. **A note for the whole build step** (the executable or library). At the start of a build, zig checks this note first. If nothing listed in it has changed, zig reports the step as `cached` and does no work. It never opens the per-file notes.

The bug is in the second note. Sometimes zig must redo a step without compiling any of its sources, for example when a library it links has changed, so it only re-links. Zig then rewrites the step’s note with the source files only, and no headers. The header list comes from compiling, and nothing was compiled.

After that, the step’s note no longer mentions `value.h`. When `value.h` changes, zig checks the note, sees no listed file changed, reports `cached`, and keeps the old binary. The binary stays stale on every later build until `.zig-cache` is deleted.

## The minimal project

| File | What it does |
| --- | --- |
| `value.h` | Defines `VALUE` |
| `main.c` | Includes `value.h` and prints `VALUE` |
| `other.c` | A static library with one function that returns a number. `main.c` prints its result too. |
| `build.zig` | Builds the library and an executable that links it |

## The script

It creates the project in `/tmp/zig-header-bug` and runs two cases. It touches nothing outside `/tmp`.

```sh
(
d=/tmp/zig-header-bug
rm -rf "$d"
mkdir -p "$d"
cd "$d" || exit 1

cat > build.zig <<'EOF'
const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const lib_mod = b.createModule(.{ .target = target, .optimize = optimize, .link_libc = true });
    lib_mod.addCSourceFile(.{ .file = b.path("other.c") });
    const lib = b.addLibrary(.{ .name = "other", .root_module = lib_mod, .linkage = .static });

    const exe_mod = b.createModule(.{ .target = target, .optimize = optimize, .link_libc = true });
    exe_mod.addCSourceFile(.{ .file = b.path("main.c") });
    exe_mod.linkLibrary(lib);
    const exe = b.addExecutable(.{ .name = "repro", .root_module = exe_mod });
    b.installArtifact(exe);
}
EOF

cat > main.c <<'EOF'
#include <stdio.h>
#include "value.h"
int other(void);
int main(void)
{
    printf("header=%d library=%d\n", VALUE, other());
    return 0;
}
EOF

setHeader() { printf '#define VALUE %s\n' "$1" > value.h; }
setLib() { printf 'int other(void) { return %s; }\n' "$1" > other.c; }
run() {
    sleep 1
    zig build --summary all 2>&1 | grep -E 'compile exe repro|error'
    printf ' output: '
    ./zig-out/bin/repro
}

echo "zig $(zig version)"

echo '=== CONTROL: header change only ==='
rm -rf .zig-cache zig-out
setHeader 1; setLib 1
echo '-- first build (expect header=1 library=1)'; run
setHeader 2
echo '-- header 1 -> 2 (expect header=2 library=1)'; run

echo '=== BUG: library change, then header change ==='
rm -rf .zig-cache zig-out
setHeader 1; setLib 1
echo '-- first build (expect header=1 library=1)'; run
setLib 2
echo '-- library 1 -> 2, program only re-linked (expect header=1 library=2)'; run
setHeader 2
echo '-- header 1 -> 2 (expect header=2 library=2)'; run
echo '-- the same build again, nothing changed (expect header=2 library=2)'; run
) 2>&1 | tee /tmp/zig-header-bug.txt

```

## How to reproduce

1. Open a terminal.
2. Paste the whole script above, from the first `(` to the last line, and press Return.
3. Read the output. It is also saved in `/tmp/zig-header-bug.txt`.

The `sleep 1` before each build keeps file times clearly apart, so the result cannot be a timing effect.

The same steps by hand, in the project folder:

1. Run `zig build`, then `./zig-out/bin/repro`. It prints `header=1 library=1`.
2. Change `other.c` to return 2, and build again. Zig re-links only, and the program prints `header=1 library=2`.
3. Change `value.h` to `#define VALUE 2`, and build again. Zig reports `cached`, and the program still prints `header=1`.

## Expected and actual

| Step | Expected | Actual |
| --- | --- | --- |
| Control: change the header only | Recompile, `header=2` | Recompile, `header=2` (correct) |
| Bug: change the library | Re-link, `header=1 library=2` | Re-link, `header=1 library=2` (correct) |
| Bug: then change the header | Recompile, `header=2 library=2` | **`cached`, `header=1 library=2`** |
| Bug: build again, no change | `header=2 library=2` | **`cached`, `header=1 library=2`** |

## Observed output (zig 0.17.0, aarch64-macos)

```zig
zig 0.17.0
=== CONTROL: header change only ===
-- first build (expect header=1 library=1)
   +- compile exe repro debug native success 125ms MaxRSS:54M
  output: header=1 library=1
-- header 1 -> 2 (expect header=2 library=1)
   +- compile exe repro debug native success 133ms MaxRSS:54M
  output: header=2 library=1
=== BUG: library change, then header change ===
-- first build (expect header=1 library=1)
   +- compile exe repro debug native success 118ms MaxRSS:54M
  output: header=1 library=1
-- library 1 -> 2, program only re-linked (expect header=1 library=2)
   +- compile exe repro debug native success 81ms MaxRSS:49M
  output: header=1 library=2
-- header 1 -> 2 (expect header=2 library=2)
   +- compile exe repro debug native cached 62ms MaxRSS:30M
  output: header=1 library=2
-- the same build again, nothing changed (expect header=2 library=2)
   +- compile exe repro debug native cached 62ms MaxRSS:30M
  output: header=1 library=2

```

## Why it matters

The build reports success and the output looks fine, but it is built from old headers. In a real project, the common trigger is a change in a linked library while the program’s own sources stay the same. A later header change then ships silently as old code.

## Workarounds

- **Clean build:** delete `.zig-cache` before a build that must be correct.
- **Header stamp:** a build step hashes every project header into a small generated source file (comments only) that each affected step compiles. Zig hashes sources by content, so a header change becomes a source change that zig cannot miss. Unchanged headers give the same file, so nothing is recompiled; the cost is a re-link of about half a second.