Skip to content
Language referenceZig 0.17.1Official documentation

Many operations in Zig trigger what is known as "Illegal Behavior" (IB). If Illegal Behavior is detected at compile-time, Zig emits a compile error and refuses to continue. Otherwise, when Illegal Behavior is not caught at compile-time, it falls into one of two categories.

Some Illegal Behavior is safety-checked: this means that the compiler will insert "safety checks" anywhere that the Illegal Behavior may occur at runtime, to determine whether it is about to happen. If it is, the safety check "fails", which triggers a panic.

All other Illegal Behavior is unchecked, meaning the compiler is unable to insert safety checks for it. If Unchecked Illegal Behavior is invoked at runtime, anything can happen: usually that will be some kind of crash, but the optimizer is free to make Unchecked Illegal Behavior do anything, such as calling arbitrary functions or clobbering arbitrary data. This is similar to the concept of "undefined behavior" in some other languages. Note that Unchecked Illegal Behavior still always results in a compile error if evaluated at comptime, because the Zig compiler is able to perform more sophisticated checks at compile-time than at runtime.

Most Illegal Behavior is safety-checked. However, to facilitate optimizations, safety checks are disabled by default in the fast and small optimization modes. Safety checks can also be enabled or disabled on a per-block basis, overriding the default for the current optimization mode, using @setRuntimeSafety. When safety checks are disabled, Safety-Checked Illegal Behavior behaves like Unchecked Illegal Behavior; that is, any behavior may result from invoking it.

When a safety check fails, Zig's default panic handler crashes with a stack trace, like this:

test_illegal_behavior.zig
test "safety check" {
unreachable;
}
Terminal
$ zig test test_illegal_behavior.zig
1/1 test_illegal_behavior.test.safety check...thread 434845 panic: reached unreachable code
/home/alexrp/Sources/ziglang/zig/doc/langref/test_illegal_behavior.zig:2:5: 0x124e95c in test.safety check (test_illegal_behavior.zig)
unreachable;
^
/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/3aa542d34ddb22d26bfe6eef53af0185/test --seed=0x130f3696

Reaching Unreachable Code

At compile-time:

test_comptime_reaching_unreachable.zig
comptime {
assert(false);
}
fn assert(ok: bool) void {
if (!ok) unreachable; // assertion failure
}
Terminal
$ zig test test_comptime_reaching_unreachable.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_reaching_unreachable.zig:5:14: error: reached unreachable code
if (!ok) unreachable; // assertion failure
^~~~~~~~~~~
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_reaching_unreachable.zig:2:11: note: called at comptime here
assert(false);
~~~~~~^~~~~~~

At runtime:

runtime_reaching_unreachable.zig
const std = @import("std");
pub fn main() void {
std.debug.assert(false);
}
Terminal
$ zig build-exe runtime_reaching_unreachable.zig
$ ./runtime_reaching_unreachable
thread 470945 panic: reached unreachable code
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/debug.zig:442:14: 0x1029e99 in assert (std.zig)
if (!ok) unreachable; // assertion failure
^
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_reaching_unreachable.zig:4:21: 0x11e3b9e in main (runtime_reaching_unreachable.zig)
std.debug.assert(false);
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

Index out of Bounds

At compile-time:

test_comptime_index_out_of_bounds.zig
comptime {
const array: [5]u8 = "hello".*;
const garbage = array[5];
_ = garbage;
}
Terminal
$ zig test test_comptime_index_out_of_bounds.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_index_out_of_bounds.zig:3:27: error: index 5 outside array of length 5
const garbage = array[5];
^

At runtime:

runtime_index_out_of_bounds.zig
pub fn main() void {
const x = foo("hello");
_ = x;
}
fn foo(x: []const u8) u8 {
return x[5];
}
Terminal
$ zig build-exe runtime_index_out_of_bounds.zig
$ ./runtime_index_out_of_bounds
thread 459826 panic: index out of bounds: index 5, len 5
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_index_out_of_bounds.zig:7:13: 0x11e3c7e in foo (runtime_index_out_of_bounds.zig)
return x[5];
^
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_index_out_of_bounds.zig:2:18: 0x11e3baa in main (runtime_index_out_of_bounds.zig)
const x = foo("hello");
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

Cast Negative Number to Unsigned Integer

At compile-time:

test_comptime_invalid_cast.zig
comptime {
const value: i32 = -1;
const unsigned: u32 = @intCast(value);
_ = unsigned;
}
Terminal
$ zig test test_comptime_invalid_cast.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_invalid_cast.zig:3:36: error: type 'u32' cannot represent integer value '-1'
const unsigned: u32 = @intCast(value);
^~~~~

At runtime:

runtime_invalid_cast.zig
const std = @import("std");
pub fn main() void {
var value: i32 = -1; // runtime-known
_ = &value;
const unsigned: u32 = @intCast(value);
std.debug.print("value: {}\n", .{unsigned});
}
Terminal
$ zig build-exe runtime_invalid_cast.zig
$ ./runtime_invalid_cast
thread 510045 panic: integer does not fit in destination type
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_invalid_cast.zig:6:27: 0x11e3baf in main (runtime_invalid_cast.zig)
const unsigned: u32 = @intCast(value);
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

To obtain the maximum value of an unsigned integer, use std.math.maxInt.

Cast Truncates Data

At compile-time:

test_comptime_invalid_cast_truncate.zig
comptime {
const spartan_count: u16 = 300;
const byte: u8 = @intCast(spartan_count);
_ = byte;
}
Terminal
$ zig test test_comptime_invalid_cast_truncate.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_invalid_cast_truncate.zig:3:31: error: type 'u8' cannot represent integer value '300'
const byte: u8 = @intCast(spartan_count);
^~~~~~~~~~~~~

At runtime:

runtime_invalid_cast_truncate.zig
const std = @import("std");
pub fn main() void {
var spartan_count: u16 = 300; // runtime-known
_ = &spartan_count;
const byte: u8 = @intCast(spartan_count);
std.debug.print("value: {}\n", .{byte});
}
Terminal
$ zig build-exe runtime_invalid_cast_truncate.zig
$ ./runtime_invalid_cast_truncate
thread 499848 panic: integer does not fit in destination type
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_invalid_cast_truncate.zig:6:22: 0x11e3bb0 in main (runtime_invalid_cast_truncate.zig)
const byte: u8 = @intCast(spartan_count);
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

To truncate bits, use @truncate.

Integer Overflow

Default Operations

The following operators can cause integer overflow:

Example with addition at compile-time:

test_comptime_overflow.zig
comptime {
var byte: u8 = 255;
byte += 1;
}
Terminal
$ zig test test_comptime_overflow.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_overflow.zig:3:10: error: overflow of integer type 'u8' with value '256'
byte += 1;
~~~~~^~~~

At runtime:

runtime_overflow.zig
const std = @import("std");
pub fn main() void {
var byte: u8 = 255;
byte += 1;
std.debug.print("value: {}\n", .{byte});
}
Terminal
$ zig build-exe runtime_overflow.zig
$ ./runtime_overflow
thread 488364 panic: integer overflow
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_overflow.zig:5:10: 0x11e3bc5 in main (runtime_overflow.zig)
byte += 1;
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

Standard Library Math Functions

These functions provided by the standard library return possible errors.

  • @import("std").math.add
  • @import("std").math.sub
  • @import("std").math.mul
  • @import("std").math.divTrunc
  • @import("std").math.divFloor
  • @import("std").math.divCeil
  • @import("std").math.divExact
  • @import("std").math.shl

Example of catching an overflow for addition:

math_add.zig
const math = @import("std").math;
const print = @import("std").debug.print;
pub fn main() !void {
var byte: u8 = 255;
byte = if (math.add(u8, byte, 1)) |result| result else |err| {
print("unable to add one: {s}\n", .{@errorName(err)});
return err;
};
print("result: {}\n", .{byte});
}
Terminal
$ zig build-exe math_add.zig
$ ./math_add
unable to add one: Overflow
error: Overflow
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/math.zig:571:21: 0x1144b64 in add__func_528 (std.zig)
if (ov[1] != 0) return error.Overflow;
^
/home/alexrp/Sources/ziglang/zig/doc/langref/math_add.zig:8:9: 0x11e2fbf in main (math_add.zig)
return err;
^

Builtin Overflow Functions

These builtins return a tuple containing whether there was an overflow (as a u1) and the possibly overflowed bits of the operation:

Example of @addWithOverflow:

addWithOverflow_builtin.zig
const print = @import("std").debug.print;
pub fn main() void {
const byte: u8 = 255;
const ov = @addWithOverflow(byte, 10);
if (ov[1] != 0) {
print("overflowed result: {}\n", .{ov[0]});
} else {
print("result: {}\n", .{ov[0]});
}
}
Terminal
$ zig build-exe addWithOverflow_builtin.zig
$ ./addWithOverflow_builtin
overflowed result: 9

Wrapping Operations

These operations have guaranteed wraparound semantics.

  • +% (wraparound addition)
  • -% (wraparound subtraction)
  • -% (wraparound negation)
  • *% (wraparound multiplication)
test_wraparound_semantics.zig
const std = @import("std");
const expectEqual = std.testing.expectEqual;
const minInt = std.math.minInt;
const maxInt = std.math.maxInt;
test "wraparound addition and subtraction" {
const x: i32 = maxInt(i32);
const min_val = x +% 1;
try expectEqual(minInt(i32), min_val);
const max_val = min_val -% 1;
try expectEqual(maxInt(i32), max_val);
}
Terminal
$ zig test test_wraparound_semantics.zig
1/1 test_wraparound_semantics.test.wraparound addition and subtraction...OK
All 1 tests passed.

Exact Left Shift Overflow

At compile-time:

test_comptime_shlExact_overflow.zig
comptime {
const x = @shlExact(@as(u8, 0b01010101), 2);
_ = x;
}
Terminal
$ zig test test_comptime_shlExact_overflow.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_shlExact_overflow.zig:2:15: error: overflow of integer type 'u8' with value '340'
const x = @shlExact(@as(u8, 0b01010101), 2);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

At runtime:

runtime_shlExact_overflow.zig
const std = @import("std");
pub fn main() void {
var x: u8 = 0b01010101; // runtime-known
_ = &x;
const y = @shlExact(x, 2);
std.debug.print("value: {}\n", .{y});
}
Terminal
$ zig build-exe runtime_shlExact_overflow.zig
$ ./runtime_shlExact_overflow
thread 434317 panic: left shift overflowed bits
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_shlExact_overflow.zig:6:5: 0x11e3bd1 in main (runtime_shlExact_overflow.zig)
const y = @shlExact(x, 2);
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

Exact Right Shift Overflow

At compile-time:

test_comptime_shrExact_overflow.zig
comptime {
const x = @shrExact(@as(u8, 0b10101010), 2);
_ = x;
}
Terminal
$ zig test test_comptime_shrExact_overflow.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_shrExact_overflow.zig:2:15: error: exact shift shifted out 1 bits
const x = @shrExact(@as(u8, 0b10101010), 2);
^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

At runtime:

runtime_shrExact_overflow.zig
const std = @import("std");
pub fn main() void {
var x: u8 = 0b10101010; // runtime-known
_ = &x;
const y = @shrExact(x, 2);
std.debug.print("value: {}\n", .{y});
}
Terminal
$ zig build-exe runtime_shrExact_overflow.zig
$ ./runtime_shrExact_overflow
thread 511225 panic: right shift overflowed bits
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_shrExact_overflow.zig:6:5: 0x11e3bba in main (runtime_shrExact_overflow.zig)
const y = @shrExact(x, 2);
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

Division by Zero

At compile-time:

test_comptime_division_by_zero.zig
comptime {
const a: i32 = 1;
const b: i32 = 0;
const c = a / b;
_ = c;
}
Terminal
$ zig test test_comptime_division_by_zero.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_division_by_zero.zig:4:19: error: division by zero here causes illegal behavior
const c = a / b;
^

At runtime:

runtime_division_by_zero.zig
const std = @import("std");
pub fn main() void {
var a: u32 = 1;
var b: u32 = 0;
_ = .{ &a, &b };
const c = a / b;
std.debug.print("value: {}\n", .{c});
}
Terminal
$ zig build-exe runtime_division_by_zero.zig
$ ./runtime_division_by_zero
thread 470623 panic: division by zero
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_division_by_zero.zig:7:17: 0x11e3bc0 in main (runtime_division_by_zero.zig)
const c = a / b;
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

Remainder Division by Zero

At compile-time:

test_comptime_remainder_division_by_zero.zig
comptime {
const a: i32 = 10;
const b: i32 = 0;
const c = a % b;
_ = c;
}
Terminal
$ zig test test_comptime_remainder_division_by_zero.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_remainder_division_by_zero.zig:4:19: error: division by zero here causes illegal behavior
const c = a % b;
^

At runtime:

runtime_remainder_division_by_zero.zig
const std = @import("std");
pub fn main() void {
var a: u32 = 10;
var b: u32 = 0;
_ = .{ &a, &b };
const c = a % b;
std.debug.print("value: {}\n", .{c});
}
Terminal
$ zig build-exe runtime_remainder_division_by_zero.zig
$ ./runtime_remainder_division_by_zero
thread 449795 panic: division by zero
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_remainder_division_by_zero.zig:7:17: 0x11e3bc0 in main (runtime_remainder_division_by_zero.zig)
const c = a % b;
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

Exact Division Remainder

At compile-time:

test_comptime_divExact_remainder.zig
comptime {
const a: u32 = 10;
const b: u32 = 3;
const c = @divExact(a, b);
_ = c;
}
Terminal
$ zig test test_comptime_divExact_remainder.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_divExact_remainder.zig:4:15: error: exact division produced remainder
const c = @divExact(a, b);
^~~~~~~~~~~~~~~

At runtime:

runtime_divExact_remainder.zig
const std = @import("std");
pub fn main() void {
var a: u32 = 10;
var b: u32 = 3;
_ = .{ &a, &b };
const c = @divExact(a, b);
std.debug.print("value: {}\n", .{c});
}
Terminal
$ zig build-exe runtime_divExact_remainder.zig
$ ./runtime_divExact_remainder
thread 454913 panic: exact division produced remainder
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_divExact_remainder.zig:7:15: 0x11e3bf5 in main (runtime_divExact_remainder.zig)
const c = @divExact(a, b);
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

Attempt to Unwrap Null

At compile-time:

test_comptime_unwrap_null.zig
comptime {
const optional_number: ?i32 = null;
const number = optional_number.?;
_ = number;
}
Terminal
$ zig test test_comptime_unwrap_null.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_unwrap_null.zig:3:35: error: unable to unwrap null
const number = optional_number.?;
~~~~~~~~~~~~~~~^~

At runtime:

runtime_unwrap_null.zig
const std = @import("std");
pub fn main() void {
var optional_number: ?i32 = null;
_ = &optional_number;
const number = optional_number.?;
std.debug.print("value: {}\n", .{number});
}
Terminal
$ zig build-exe runtime_unwrap_null.zig
$ ./runtime_unwrap_null
thread 459861 panic: attempt to use null value
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_unwrap_null.zig:6:35: 0x11e3bc4 in main (runtime_unwrap_null.zig)
const number = optional_number.?;
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

One way to avoid this crash is to test for null instead of assuming non-null, with the if expression:

testing_null_with_if.zig
const print = @import("std").debug.print;
pub fn main() void {
const optional_number: ?i32 = null;
if (optional_number) |number| {
print("got number: {}\n", .{number});
} else {
print("it's null\n", .{});
}
}
Terminal
$ zig build-exe testing_null_with_if.zig
$ ./testing_null_with_if
it's null

See also:

Attempt to Unwrap Error

At compile-time:

test_comptime_unwrap_error.zig
comptime {
const number = getNumberOrFail() catch unreachable;
_ = number;
}
fn getNumberOrFail() !i32 {
return error.UnableToReturnNumber;
}
Terminal
$ zig test test_comptime_unwrap_error.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_unwrap_error.zig:2:44: error: caught unexpected error 'UnableToReturnNumber'
const number = getNumberOrFail() catch unreachable;
^~~~~~~~~~~
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_unwrap_error.zig:7:18: note: error returned here
return error.UnableToReturnNumber;
^~~~~~~~~~~~~~~~~~~~

At runtime:

runtime_unwrap_error.zig
const std = @import("std");
pub fn main() void {
const number = getNumberOrFail() catch unreachable;
std.debug.print("value: {}\n", .{number});
}
fn getNumberOrFail() !i32 {
return error.UnableToReturnNumber;
}
Terminal
$ zig build-exe runtime_unwrap_error.zig
$ ./runtime_unwrap_error
thread 459242 panic: attempt to unwrap error: UnableToReturnNumber
error return context:
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_unwrap_error.zig:9:5: 0x11e3b9c in getNumberOrFail (runtime_unwrap_error.zig)
return error.UnableToReturnNumber;
^
stack trace:
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_unwrap_error.zig:4:44: 0x11e3c03 in main (runtime_unwrap_error.zig)
const number = getNumberOrFail() catch unreachable;
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

One way to avoid this crash is to test for an error instead of assuming a successful result, with the if expression:

testing_error_with_if.zig
const print = @import("std").debug.print;
pub fn main() void {
const result = getNumberOrFail();
if (result) |number| {
print("got number: {}\n", .{number});
} else |err| {
print("got error: {s}\n", .{@errorName(err)});
}
}
fn getNumberOrFail() !i32 {
return error.UnableToReturnNumber;
}
Terminal
$ zig build-exe testing_error_with_if.zig
$ ./testing_error_with_if
got error: UnableToReturnNumber

See also:

Invalid Error Code

At compile-time:

test_comptime_invalid_error_code.zig
comptime {
_ = @errorFromInt(12345);
}
Terminal
$ zig test test_comptime_invalid_error_code.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_invalid_error_code.zig:2:23: error: integer value '12345' represents no error
_ = @errorFromInt(12345);
^~~~~

At runtime:

runtime_invalid_error_code.zig
const std = @import("std");
pub fn main() void {
const err = error.AnError;
var number = @intFromError(err) + 500;
_ = &number;
const invalid_err = @errorFromInt(number);
std.debug.print("value: {}\n", .{invalid_err});
}
Terminal
$ zig build-exe runtime_invalid_error_code.zig
$ ./runtime_invalid_error_code
thread 449206 panic: invalid error code
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_invalid_error_code.zig:7:5: 0x11e3bd5 in main (runtime_invalid_error_code.zig)
const invalid_err = @errorFromInt(number);
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

Invalid Enum Cast

At compile-time:

test_comptime_invalid_enum_cast.zig
const Foo = enum(u2) {
a,
b,
c,
};
comptime {
const a: u2 = 3;
const b: Foo = @fromBackingInt(a);
_ = b;
}
Terminal
$ zig test test_comptime_invalid_enum_cast.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_invalid_enum_cast.zig:8:20: error: enum 'test_comptime_invalid_enum_cast.Foo' has no tag with value '3'
const b: Foo = @fromBackingInt(a);
^~~~~~~~~~~~~~~~~~
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_invalid_enum_cast.zig:1:13: note: enum declared here
const Foo = enum(u2) {
^~~~

At runtime:

runtime_invalid_enum_cast.zig
const std = @import("std");
const Foo = enum(u2) {
a,
b,
c,
};
fn foo(a: u2) void {
const b: Foo = @fromBackingInt(a);
std.debug.print("value: {s}\n", .{@tagName(b)});
}
pub fn main() void {
foo(3);
}
Terminal
$ zig build-exe runtime_invalid_enum_cast.zig
$ ./runtime_invalid_enum_cast
thread 450042 panic: invalid enum value
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_invalid_enum_cast.zig:10:20: 0x11e3cab in foo (runtime_invalid_enum_cast.zig)
const b: Foo = @fromBackingInt(a);
^
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_invalid_enum_cast.zig:15:8: 0x11e3b9e in main (runtime_invalid_enum_cast.zig)
foo(3);
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

Invalid Error Set Cast

At compile-time:

test_comptime_invalid_error_set_cast.zig
const Set1 = error{
A,
B,
};
const Set2 = error{
A,
C,
};
comptime {
_ = @as(Set2, @errorCast(Set1.B));
}
Terminal
$ zig test test_comptime_invalid_error_set_cast.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_invalid_error_set_cast.zig:10:19: error: 'error.B' not a member of error set 'error{A,C}'
_ = @as(Set2, @errorCast(Set1.B));
^~~~~~~~~~~~~~~~~~

At runtime:

runtime_invalid_error_set_cast.zig
const std = @import("std");
const Set1 = error{
A,
B,
};
const Set2 = error{
A,
C,
};
pub fn main() void {
foo(Set1.B);
}
fn foo(set1: Set1) void {
const x: Set2 = @errorCast(set1);
std.debug.print("value: {}\n", .{x});
}
Terminal
$ zig build-exe runtime_invalid_error_set_cast.zig
$ ./runtime_invalid_error_set_cast
thread 438289 panic: unexpected error code, found error.B
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_invalid_error_set_cast.zig:15:21: 0x11e3ca1 in foo (runtime_invalid_error_set_cast.zig)
const x: Set2 = @errorCast(set1);
^
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_invalid_error_set_cast.zig:12:8: 0x11e3ba7 in main (runtime_invalid_error_set_cast.zig)
foo(Set1.B);
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

Incorrect Pointer Alignment

At compile-time:

test_comptime_incorrect_pointer_alignment.zig
comptime {
const ptr: *align(1) i32 = @ptrFromInt(0x1);
const aligned: *align(4) i32 = @alignCast(ptr);
_ = aligned;
}
Terminal
$ zig test test_comptime_incorrect_pointer_alignment.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_incorrect_pointer_alignment.zig:3:47: error: pointer address 0x1 is not aligned to 4 bytes
const aligned: *align(4) i32 = @alignCast(ptr);
^~~

At runtime:

runtime_incorrect_pointer_alignment.zig
const mem = @import("std").mem;
pub fn main() !void {
var array align(4) = [_]u32{ 0x11111111, 0x11111111 };
const bytes = mem.sliceAsBytes(array[0..]);
if (foo(bytes) != 0x11111111) return error.Wrong;
}
fn foo(bytes: []u8) u32 {
const slice4 = bytes[1..5];
const int_slice = mem.bytesAsSlice(u32, @as([]align(4) u8, @alignCast(slice4)));
return int_slice[0];
}
Terminal
$ zig build-exe runtime_incorrect_pointer_alignment.zig
$ ./runtime_incorrect_pointer_alignment
thread 510534 panic: incorrect alignment
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_incorrect_pointer_alignment.zig:9:64: 0x11e4586 in foo (runtime_incorrect_pointer_alignment.zig)
const int_slice = mem.bytesAsSlice(u32, @as([]align(4) u8, @alignCast(slice4)));
^
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_incorrect_pointer_alignment.zig:5:12: 0x11e2f5e in main (runtime_incorrect_pointer_alignment.zig)
if (foo(bytes) != 0x11111111) return error.Wrong;
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e3576 in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

Wrong Union Field Access

At compile-time:

test_comptime_wrong_union_field_access.zig
comptime {
var f = Foo{ .int = 42 };
f.float = 12.34;
}
const Foo = union {
float: f32,
int: u32,
};
Terminal
$ zig test test_comptime_wrong_union_field_access.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_wrong_union_field_access.zig:3:6: error: access of union field 'float' while field 'int' is active
f.float = 12.34;
~^~~~~~
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_wrong_union_field_access.zig:6:13: note: union declared here
const Foo = union {
^~~~~

At runtime:

runtime_wrong_union_field_access.zig
const std = @import("std");
const Foo = union {
float: f32,
int: u32,
};
pub fn main() void {
var f = Foo{ .int = 42 };
bar(&f);
}
fn bar(f: *Foo) void {
f.float = 12.34;
std.debug.print("value: {}\n", .{f.float});
}
Terminal
$ zig build-exe runtime_wrong_union_field_access.zig
$ ./runtime_wrong_union_field_access
thread 481177 panic: access of union field 'float' while field 'int' is active
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_wrong_union_field_access.zig:14:6: 0x11e3c6e in bar (runtime_wrong_union_field_access.zig)
f.float = 12.34;
^
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_wrong_union_field_access.zig:10:8: 0x11e3bae in main (runtime_wrong_union_field_access.zig)
bar(&f);
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

This safety is not available for extern or packed unions.

To change the active field of a union, assign the entire union, like this:

change_active_union_field.zig
const std = @import("std");
const Foo = union {
float: f32,
int: u32,
};
pub fn main() void {
var f = Foo{ .int = 42 };
bar(&f);
}
fn bar(f: *Foo) void {
f.* = Foo{ .float = 12.34 };
std.debug.print("value: {}\n", .{f.float});
}
Terminal
$ zig build-exe change_active_union_field.zig
$ ./change_active_union_field
value: 12.34

To change the active field of a union when a meaningful value for the field is not known, use undefined, like this:

undefined_active_union_field.zig
const std = @import("std");
const Foo = union {
float: f32,
int: u32,
};
pub fn main() void {
var f = Foo{ .int = 42 };
f = Foo{ .float = undefined };
bar(&f);
std.debug.print("value: {}\n", .{f.float});
}
fn bar(f: *Foo) void {
f.float = 12.34;
}
Terminal
$ zig build-exe undefined_active_union_field.zig
$ ./undefined_active_union_field
value: 12.34

See also:

Out of Bounds Float to Integer Cast

This happens when casting a float to an integer where the float has a value outside the integer type's range.

At compile-time:

test_comptime_out_of_bounds_float_to_integer_cast.zig
comptime {
const float: f32 = 4294967296;
const int: i32 = @intFromFloat(float);
_ = int;
}
Terminal
$ zig test test_comptime_out_of_bounds_float_to_integer_cast.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_out_of_bounds_float_to_integer_cast.zig:3:36: error: float value '4294967296' cannot be stored in integer type 'i32'
const int: i32 = @intFromFloat(float);
^~~~~

At runtime:

runtime_out_of_bounds_float_to_integer_cast.zig
pub fn main() void {
var float: f32 = 4294967296; // runtime-known
_ = &float;
const int: i32 = @intFromFloat(float);
_ = int;
}
Terminal
$ zig build-exe runtime_out_of_bounds_float_to_integer_cast.zig
$ ./runtime_out_of_bounds_float_to_integer_cast
thread 438431 panic: integer part of floating point value out of bounds
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_out_of_bounds_float_to_integer_cast.zig:4:22: 0x11e3bde in main (runtime_out_of_bounds_float_to_integer_cast.zig)
const int: i32 = @intFromFloat(float);
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)

Pointer Cast Invalid Null

This happens when casting a pointer with the address 0 to a pointer which may not have the address 0. For example, C Pointers, Optional Pointers, and allowzero pointers allow address zero, but normal Pointers do not.

At compile-time:

test_comptime_invalid_null_pointer_cast.zig
comptime {
const opt_ptr: ?*i32 = null;
const ptr: *i32 = @ptrCast(opt_ptr);
_ = ptr;
}
Terminal
$ zig test test_comptime_invalid_null_pointer_cast.zig
/home/alexrp/Sources/ziglang/zig/doc/langref/test_comptime_invalid_null_pointer_cast.zig:3:32: error: null pointer casted to type '*i32'
const ptr: *i32 = @ptrCast(opt_ptr);
^~~~~~~

At runtime:

runtime_invalid_null_pointer_cast.zig
pub fn main() void {
var opt_ptr: ?*i32 = null;
_ = &opt_ptr;
const ptr: *i32 = @ptrCast(opt_ptr);
_ = ptr;
}
Terminal
$ zig build-exe runtime_invalid_null_pointer_cast.zig
$ ./runtime_invalid_null_pointer_cast
thread 450094 panic: cast causes pointer to be null
/home/alexrp/Sources/ziglang/zig/doc/langref/runtime_invalid_null_pointer_cast.zig:4:23: 0x11e3bba in main (runtime_invalid_null_pointer_cast.zig)
const ptr: *i32 = @ptrCast(opt_ptr);
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:788:64: 0x11e34cb in callMain (std.zig)
if (fn_info.param_types.len == 0) return wrapMain(root.main());
^
/home/alexrp/.cache/zig/p/N-V-__8AALBXTRYsilzupvrmv0afm7ohtj5Mj0paqVfKLmfP/lib/std/start.zig:248:5: 0x11e2f01 in _start (std.zig)
asm volatile (switch (native_arch) {
^
(process terminated by signal)