Skip to content
Language referenceZig 0.17.1Official documentation

In debug and safe mode unreachable emits a call to panic with the message reached unreachable code.

In fast and small mode, the optimizer uses the assumption that unreachable code will never be hit to perform optimizations.

Basics

test_unreachable.zig
// unreachable is used to assert that control flow will never reach a
// particular location:
test "basic math" {
const x = 1;
const y = 2;
if (x + y != 3) {
unreachable;
}
}
Terminal
$ zig test test_unreachable.zig
1/1 test_unreachable.test.basic math...OK
All 1 tests passed.

In fact, this is how std.debug.assert is implemented:

test_assertion_failure.zig
// This is how std.debug.assert is implemented
fn assert(ok: bool) void {
if (!ok) unreachable; // assertion failure
}
// This test will fail because we hit unreachable.
test "this will fail" {
assert(false);
}
Terminal
$ zig test test_assertion_failure.zig
1/1 test_assertion_failure.test.this will fail...thread 471146 panic: reached unreachable code
/home/alexrp/Sources/ziglang/zig/doc/langref/test_assertion_failure.zig:3:14: 0x124e989 in assert (test_assertion_failure.zig)
if (!ok) unreachable; // assertion failure
^
/home/alexrp/Sources/ziglang/zig/doc/langref/test_assertion_failure.zig:8:11: 0x124e95e in test.this will fail (test_assertion_failure.zig)
assert(false);
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/compiler/test_runner.zig:295:25: 0x1202c41 in mainTerminal (test_runner.zig)
if (test_fn.func()) |_| {
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/compiler/test_runner.zig:74:28: 0x1202422 in main (test_runner.zig)
return mainTerminal(init);
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:789:88: 0x11febbf in callMain (std.zig)
if (fn_info.param_types[0].? == std.process.Init.Minimal) return wrapMain(root.main(.{
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11fe5a1 in _start (std.zig)
asm volatile (switch (native_arch) {
^
error: the following test command terminated with signal ABRT:
/home/alexrp/Sources/ziglang/zig/.zig-cache/o/a13112c1fe2007cebe044e6075fbf8aa/test --seed=0x578a2438

At Compile-Time

test_comptime_unreachable.zig
const assert = @import("std").debug.assert;
test "type of unreachable" {
comptime {
// The type of unreachable is noreturn.
// However this assertion will still fail to compile because
// unreachable expressions are compile errors.
assert(@TypeOf(unreachable) == noreturn);
}
}
Terminal
$ zig test test_comptime_unreachable.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_unreachable.zig:10:16: error: unreachable code
assert(@TypeOf(unreachable) == noreturn);
^~~~~~~~~~~~~~~~~~~~
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_unreachable.zig:10:24: note: control flow is diverted here
assert(@TypeOf(unreachable) == noreturn);
^~~~~~~~~~~

See also: