Zig "the following command failed" in zig build in CI

By Kaveh Alemi·Latchkey

zig build runs a graph of steps. When any step (a compiled binary you run, a test, or an external command) exits non-zero, Zig prints "the following command failed" with the exact command line it ran.

What this error means

zig build ends with "error: the following command failed with exit code N:" followed by the full command, so you can reproduce the failing step directly.

error: the following command failed with exit code 1:
/home/runner/work/app/app/zig-out/bin/gen-config config.zon

Common causes

A run or test step exited non-zero

A step that executes a binary or test failed, and zig build surfaces that exit code rather than hiding it.

An external command in the build graph failed

A custom step that shells out to another tool returned non-zero, failing the overall build.

How to fix it

Run the printed command directly

1. Copy the exact command line Zig printed after the error.
2. Run it in the same directory to see its own output and exit code.
3. Fix the underlying step (the program logic, missing input, or a failing test).

./zig-out/bin/gen-config config.zon   # reproduce the failing step

Get more detail from the build

Re-run with verbose output to see each step the build graph executed.

zig build --verbose

How to prevent it

• Reproduce a failing step by running the printed command locally.
• Keep build steps deterministic so failures are reproducible.
• Use --verbose to see the full step graph when diagnosing.

Frequently asked questions

Related guides

References

• GitHub Actions documentation