misleading error message from build runner caused by failed build step #2572
Description
This following build script will fail to compile:
const std = @import("std");
pub fn build(b: *std.Build) void {
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});
const generator = b.addExecutable(.{
.name = "generator",
.root_module = b.createModule(.{
.root_source_file = b.addWriteFiles().add("generator.zig",
\\pub const main = @compileError("some compile error");
),
.target = target,
.optimize = optimize,
}),
});
const generated = b.addRunArtifact(generator).addOutputFileArg("generated.zig");
const exe = b.addExecutable(.{
.name = "exe",
.root_module = b.createModule(.{
.root_source_file = generated,
.target = target,
.optimize = optimize,
}),
});
b.installArtifact(exe);
}Running zig build will report the following output as expected:
install
└─ install exe
└─ compile exe exe Debug native
└─ run exe generator (generated.zig)
└─ compile exe generator Debug native 1 errors
.zig-cache/o/3765f0ec1faa1bdb4e14fa364aacd880/generator.zig:1:18: error: some compile error
pub const main = @compileError("some compile error");
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
referenced by:
callMain [inlined]: /home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/lib/std/start.zig:674:43
callMainWithArgs [inlined]: /home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/lib/std/start.zig:626:20
posixCallMainAndExit: /home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/lib/std/start.zig:581:38
2 reference(s) hidden; use '-freference-trace=5' to see all references
error: 1 compilation errors
failed command: /home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/zig build-exe -ODebug -Mroot=.zig-cache/o/3765f0ec1faa1bdb4e14fa364aacd880/generator.zig --cache-dir .zig-cache --global-cache-dir /home/techatrix/.cache/zig --name generator --zig-lib-dir /home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/lib/ --listen=-
Build Summary: 1/6 steps succeeded (1 failed)
install transitive failure
└─ install exe transitive failure
└─ compile exe exe Debug native transitive failure
└─ run exe generator (generated.zig) transitive failure
└─ compile exe generator Debug native 1 errors
error: the following build command failed with exit code 1:
.zig-cache/o/412b82bed3acb02e7b91f094c6ee3265/build /home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/zig /home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/lib /home/techatrix/repos/a-techatrix/zig-testspace .zig-cache /home/techatrix/.cache/zig --seed 0xc7d8c8ed -Z106827ba0b57b4c1
The ZLS build runner will however report a completely different error message that very misleading.
2026-01-16 15:08:27.505 [info] Starting ZLS 0.16.0-dev.130+ea5418b1 @ '/home/techatrix/repos/zls/zig-out/bin/zls'
2026-01-16 15:08:27.505 [info] Log File: /home/techatrix/.cache/zls/zls.log (debug)
2026-01-16 15:08:27.505 [info] Client Info: VSCodium (1.106.2)
2026-01-16 15:08:27.506 [info] added Workspace Folder: file:///home/techatrix/repos/a-techatrix/zig-testspace
2026-01-16 15:08:27.513 [info] Server process exited successfully
2026-01-16 15:08:27.513 [info] Loaded build file 'file:///home/techatrix/repos/a-techatrix/zig-testspace/build.zig'
2026-01-16 15:08:27.522 [info] Set config option 'build_on_save_args' to ["-fincremental"]
2026-01-16 15:08:27.522 [info] Set config option 'semantic_tokens' to "partial"
2026-01-16 15:08:27.523 [info] Set config option 'builtin_path' to "/home/techatrix/.cache/zls/builtin.zig"
2026-01-16 15:08:27.523 [info] Set config option 'zig_lib_path' to "/home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/lib"
2026-01-16 15:08:27.523 [info] Set config option 'zig_exe_path' to "/home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/zig"
2026-01-16 15:08:27.523 [info] Set config option 'build_runner_path' to "/home/techatrix/repos/zls/src/build_runner/build_runner.zig"
2026-01-16 15:08:27.523 [info] Set config option 'global_cache_path' to "/home/techatrix/.cache/zls"
2026-01-16 15:08:27.524 [info] trying to start Build-On-Save for 'file:///home/techatrix/repos/a-techatrix/zig-testspace'
2026-01-16 15:08:28.291 [error] Failed to execute build runner to collect build configuration, command:
cd /home/techatrix/repos/a-techatrix/zig-testspace;/home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/zig build --build-runner /home/techatrix/repos/zls/src/build_runner/build_runner.zig --zig-lib-dir /home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/lib
Error: getPath() was called on a GeneratedFile that wasn't built yet.
source package path: /home/techatrix/repos/a-techatrix/zig-testspace
Is there a missing Step dependency on step 'run exe generator (generated.zig)'?
The step was created by this stack trace:
name: 'run exe generator (generated.zig)'. creation stack trace:
/home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/lib/std/Build/Step/Run.zig:210:22: 0x12a2ca2 in create (std.zig)
.step = .init(.{
^
/home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/lib/std/Build.zig:941:37: 0x12729fd in addRunArtifact (std.zig)
const run_step = Step.Run.create(b, step_name);
^
/home/techatrix/repos/a-techatrix/zig-testspace/build.zig:17:39: 0x124d758 in build (build.zig)
const generated = b.addRunArtifact(generator).addOutputFileArg("generated.zig");
^
/home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/lib/std/Build.zig:2258:33: 0x12128ea in runBuild__anon_31015 (std.zig)
.void => build_zig.build(b),
^
/home/techatrix/repos/zls/src/build_runner/build_runner.zig:332:29: 0x11f9bb0 in main (build_runner.zig)
try builder.runBuild(root);
^
/home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/lib/std/start.zig:676:88: 0x11fd42d in callMain (std.zig)
if (fn_info.params[0].type.? == std.process.Init.Minimal) return wrapMain(root.main(.{
^
/home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/lib/std/start.zig:190:5: 0x11e8651 in _start (std.zig)
asm volatile (switch (native_arch) {
^
Proceeding to panic.
thread 11772 panic: misconfigured build script
/home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/lib/std/Build.zig:2515:25: 0x12aa140 in getPath4 (std.zig)
@panic("misconfigured build script");
^
/home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/lib/std/Build.zig:2483:24: 0x1278dcd in getPath3 (std.zig)
return getPath4(lazy_path, src_builder, asking_step) catch |err| switch (err) {
^
/home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/lib/std/Build.zig:2477:27: 0x12539fd in getPath2 (std.zig)
const p = getPath3(lazy_path, src_builder, asking_step);
^
/home/techatrix/.config/VSCodium/User/globalStorage/ziglang.vscode-zig/zig/x86_64-linux-0.16.0-dev.2205+d86e8b779/lib/std/Build.zig:2472:24: 0x1217127 in getPath (std.zig)
return getPath2(lazy_path, src_builder, null);
^
/home/techatrix/repos/zls/src/build_runner/build_runner.zig:1117:75: 0x11ecc78 in processItem (build_runner.zig)
_ = try packages.addPackage(name, root_source_file.getPath(module.owner));
^
/home/techatrix/repos/zls/src/build_runner/build_...