Undefined Behavior

Undefined Behavior

Zig has many instances of undefined behavior. If undefined behavior is detected at compile-time, Zig emits a compile error and refuses to continue. Most undefined behavior that cannot be detected at compile-time can be detected at runtime. In these cases, Zig has safety checks. Safety checks can be disabled on a per-block basis with @setRuntimeSafety. The ReleaseFast and ReleaseSmall build modes disable all safety checks (except where overridden by @setRuntimeSafety) in order to facilitate optimizations.

When a safety check fails, Zig crashes with a stack trace, like this:

test.zig

test "safety check" {
    unreachable;
}

$ zig test test.zig
Test [1/1] test "safety check"... 
thread 16425 panic: reached unreachable code
/home/andy/Downloads/zig/docgen_tmp/test.zig:2:5: 0x2066ea in test "safety check" (test)
    unreachable;
    ^
/home/andy/Downloads/zig/lib/std/special/test_runner.zig:76:28: 0x22cfca in std.special.main (test)
        } else test_fn.func();
                           ^
/home/andy/Downloads/zig/lib/std/start.zig:471:37: 0x22552a in std.start.callMain (test)
            const result = root.main() catch |err| {
                                    ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x2093ae in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x2083d6 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x2081e2 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
error: the following test command crashed:
docgen_tmp/zig-cache/o/333a8741816702dafd0ff99af380ebb1/test /home/andy/Downloads/zig/build-release/zig

Reaching Unreachable Code

At compile-time:

test.zig

comptime {
    assert(false);
}
fn assert(ok: bool) void {
    if (!ok) unreachable; // assertion failure
}

$ zig test test.zig
./docgen_tmp/test.zig:5:14: error: reached unreachable code
    if (!ok) unreachable; // assertion failure
             ^
./docgen_tmp/test.zig:2:11: note: called from here
    assert(false);
          ^
./docgen_tmp/test.zig:1:10: note: called from here
comptime {
         ^
./docgen_tmp/test.zig:2:11: note: referenced here
    assert(false);
          ^

At runtime:

test.zig

const std = @import("std");
pub fn main() void {
    std.debug.assert(false);
}

$ zig build-exe test.zig
$ ./test
thread 16491 panic: reached unreachable code
/home/andy/Downloads/zig/lib/std/debug.zig:226:14: 0x2042cb in std.debug.assert (test)
    if (!ok) unreachable; // assertion failure
             ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:4:21: 0x229eea in main (test)
    std.debug.assert(false);
                    ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x2222cc in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x20615e in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x205186 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x204f92 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(process terminated by signal)

Index out of Bounds

At compile-time:

test.zig

comptime {
    const array: [5]u8 = "hello".*;
    const garbage = array[5];
}

$ zig test test.zig
./docgen_tmp/test.zig:3:26: error: index 5 outside array of size 5
    const garbage = array[5];
                         ^

At runtime:

test.zig

pub fn main() void {
    var x = foo("hello");
}
fn foo(x: []const u8) u8 {
    return x[5];
}

$ zig build-exe test.zig
$ ./test
thread 16553 panic: index out of bounds
/home/andy/Downloads/zig/docgen_tmp/test.zig:6:13: 0x231179 in foo (test)
    return x[5];
            ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:2:16: 0x229f06 in main (test)
    var x = foo("hello");
               ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x2222dc in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x20616e in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x205196 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x204fa2 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(process terminated by signal)

Cast Negative Number to Unsigned Integer

At compile-time:

test.zig

comptime {
    const value: i32 = -1;
    const unsigned = @intCast(u32, value);
}

$ zig test test.zig
./docgen_tmp/test.zig:3:22: error: attempt to cast negative value to unsigned integer
    const unsigned = @intCast(u32, value);
                     ^

At runtime:

test.zig

const std = @import("std");
pub fn main() void {
    var value: i32 = -1;
    var unsigned = @intCast(u32, value);
    std.debug.print("value: {}\n", .{unsigned});
}

$ zig build-exe test.zig
$ ./test
thread 16614 panic: attempt to cast negative value to unsigned integer
/home/andy/Downloads/zig/docgen_tmp/test.zig:5:20: 0x229f77 in main (test)
    var unsigned = @intCast(u32, value);
                   ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x22231c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x2061ae in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x2051d6 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x204fe2 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(process terminated by signal)

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

Cast Truncates Data

At compile-time:

test.zig

comptime {
    const spartan_count: u16 = 300;
    const byte = @intCast(u8, spartan_count);
}

$ zig test test.zig
./docgen_tmp/test.zig:3:18: error: cast from 'u16' to 'u8' truncates bits
    const byte = @intCast(u8, spartan_count);
                 ^

At runtime:

test.zig

const std = @import("std");
pub fn main() void {
    var spartan_count: u16 = 300;
    const byte = @intCast(u8, spartan_count);
    std.debug.print("value: {}\n", .{byte});
}

$ zig build-exe test.zig
$ ./test
thread 16677 panic: integer cast truncated bits
/home/andy/Downloads/zig/docgen_tmp/test.zig:5:18: 0x229f7c in main (test)
    const byte = @intCast(u8, spartan_count);
                 ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x22231c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x2061ae in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x2051d6 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x204fe2 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(process terminated by signal)

To truncate bits, use @truncate.

Integer Overflow

Default Operations

The following operators can cause integer overflow:

+ (addition)
- (subtraction)
- (negation)
* (multiplication)
/ (division)
@divTrunc (division)
@divFloor (division)
@divExact (division)

Example with addition at compile-time:

test.zig

comptime {
    var byte: u8 = 255;
    byte += 1;
}

$ zig test test.zig
./docgen_tmp/test.zig:3:10: error: operation caused overflow
    byte += 1;
         ^

At runtime:

test.zig

const std = @import("std");
pub fn main() void {
    var byte: u8 = 255;
    byte += 1;
    std.debug.print("value: {}\n", .{byte});
}

$ zig build-exe test.zig
$ ./test
thread 16739 panic: integer overflow
/home/andy/Downloads/zig/docgen_tmp/test.zig:5:10: 0x229f5f in main (test)
    byte += 1;
         ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x22231c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x2061ae in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x2051d6 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x204fe2 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(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.divExact
@import("std").math.shl

Example of catching an overflow for addition:

test.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});
}

$ zig build-exe test.zig
$ ./test
unable to add one: Overflow
error: Overflow
/home/andy/Downloads/zig/lib/std/math.zig:449:5: 0x2315ab in std.math.add (test)
    return if (@addWithOverflow(T, a, b, &answer)) error.Overflow else answer;
    ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:8:9: 0x22a244 in main (test)
        return err;
        ^

Builtin Overflow Functions

These builtins return a bool of whether or not overflow occurred, as well as returning the overflowed bits:

@addWithOverflow
@subWithOverflow
@mulWithOverflow
@shlWithOverflow

Example of @addWithOverflow:

test.zig

const print = @import("std").debug.print;
pub fn main() void {
    var byte: u8 = 255;
    var result: u8 = undefined;
    if (@addWithOverflow(u8, byte, 10, &result)) {
        print("overflowed result: {}\n", .{result});
    } else {
        print("result: {}\n", .{result});
    }
}

$ zig build-exe test.zig
$ ./test
overflowed result: 9

Wrapping Operations

These operations have guaranteed wraparound semantics.

+% (wraparound addition)
-% (wraparound subtraction)
-% (wraparound negation)
*% (wraparound multiplication)

test.zig

const std = @import("std");
const expect = std.testing.expect;
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 expect(min_val == minInt(i32));
    const max_val = min_val -% 1;
    try expect(max_val == maxInt(i32));
}

$ zig test test.zig
Test [1/1] test "wraparound addition and subtraction"... 
All 1 tests passed.

Exact Left Shift Overflow

At compile-time:

test.zig

comptime {
    const x = @shlExact(@as(u8, 0b01010101), 2);
}

$ zig test test.zig
./docgen_tmp/test.zig:2:15: error: operation caused overflow
    const x = @shlExact(@as(u8, 0b01010101), 2);
              ^

At runtime:

test.zig

const std = @import("std");
pub fn main() void {
    var x: u8 = 0b01010101;
    var y = @shlExact(x, 2);
    std.debug.print("value: {}\n", .{y});
}

$ zig build-exe test.zig
$ ./test
thread 16945 panic: left shift overflowed bits
/home/andy/Downloads/zig/docgen_tmp/test.zig:5:13: 0x229f9b in main (test)
    var y = @shlExact(x, 2);
            ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x22233c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x2061ce in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x2051f6 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x205002 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(process terminated by signal)

Exact Right Shift Overflow

At compile-time:

test.zig

comptime {
    const x = @shrExact(@as(u8, 0b10101010), 2);
}

$ zig test test.zig
./docgen_tmp/test.zig:2:15: error: exact shift shifted out 1 bits
    const x = @shrExact(@as(u8, 0b10101010), 2);
              ^

At runtime:

test.zig

const std = @import("std");
pub fn main() void {
    var x: u8 = 0b10101010;
    var y = @shrExact(x, 2);
    std.debug.print("value: {}\n", .{y});
}

$ zig build-exe test.zig
$ ./test
thread 17005 panic: right shift overflowed bits
/home/andy/Downloads/zig/docgen_tmp/test.zig:5:13: 0x229f9b in main (test)
    var y = @shrExact(x, 2);
            ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x22233c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x2061ce in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x2051f6 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x205002 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(process terminated by signal)

Division by Zero

At compile-time:

test.zig

comptime {
    const a: i32 = 1;
    const b: i32 = 0;
    const c = a / b;
}

$ zig test test.zig
./docgen_tmp/test.zig:4:17: error: division by zero
    const c = a / b;
                ^

At runtime:

test.zig

const std = @import("std");
pub fn main() void {
    var a: u32 = 1;
    var b: u32 = 0;
    var c = a / b;
    std.debug.print("value: {}\n", .{c});
}

$ zig build-exe test.zig
$ ./test
thread 17071 panic: division by zero
/home/andy/Downloads/zig/docgen_tmp/test.zig:6:15: 0x229f69 in main (test)
    var c = a / b;
              ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x22231c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x2061ae in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x2051d6 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x204fe2 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(process terminated by signal)

Remainder Division by Zero

At compile-time:

test.zig

comptime {
    const a: i32 = 10;
    const b: i32 = 0;
    const c = a % b;
}

$ zig test test.zig
./docgen_tmp/test.zig:4:17: error: division by zero
    const c = a % b;
                ^

At runtime:

test.zig

const std = @import("std");
pub fn main() void {
    var a: u32 = 10;
    var b: u32 = 0;
    var c = a % b;
    std.debug.print("value: {}\n", .{c});
}

$ zig build-exe test.zig
$ ./test
thread 17131 panic: remainder division by zero or negative value
/home/andy/Downloads/zig/docgen_tmp/test.zig:6:15: 0x229f8b in main (test)
    var c = a % b;
              ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x22231c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x2061ae in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x2051d6 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x204fe2 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(process terminated by signal)

Exact Division Remainder

At compile-time:

test.zig

comptime {
    const a: u32 = 10;
    const b: u32 = 3;
    const c = @divExact(a, b);
}

$ zig test test.zig
./docgen_tmp/test.zig:4:15: error: exact division had a remainder
    const c = @divExact(a, b);
              ^

At runtime:

test.zig

const std = @import("std");
pub fn main() void {
    var a: u32 = 10;
    var b: u32 = 3;
    var c = @divExact(a, b);
    std.debug.print("value: {}\n", .{c});
}

$ zig build-exe test.zig
$ ./test
thread 17193 panic: exact division produced remainder
/home/andy/Downloads/zig/docgen_tmp/test.zig:6:13: 0x229fad in main (test)
    var c = @divExact(a, b);
            ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x22231c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x2061ae in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x2051d6 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x204fe2 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(process terminated by signal)

Attempt to Unwrap Null

At compile-time:

test.zig

comptime {
    const optional_number: ?i32 = null;
    const number = optional_number.?;
}

$ zig test test.zig
./docgen_tmp/test.zig:3:35: error: unable to unwrap null
    const number = optional_number.?;
                                  ^

At runtime:

test.zig

const std = @import("std");
pub fn main() void {
    var optional_number: ?i32 = null;
    var number = optional_number.?;
    std.debug.print("value: {}\n", .{number});
}

$ zig build-exe test.zig
$ ./test
thread 17271 panic: attempt to use null value
/home/andy/Downloads/zig/docgen_tmp/test.zig:5:33: 0x229f6c in main (test)
    var number = optional_number.?;
                                ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x22232c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x2061be in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x2051e6 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x204ff2 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(process terminated by signal)

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

test.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", .{});
    }
}

$ zig build-exe test.zig
$ ./test
it's null

Attempt to Unwrap Error

At compile-time:

test.zig

comptime {
    const number = getNumberOrFail() catch unreachable;
}
fn getNumberOrFail() !i32 {
    return error.UnableToReturnNumber;
}

$ zig test test.zig
./docgen_tmp/test.zig:2:38: error: caught unexpected error 'UnableToReturnNumber'
    const number = getNumberOrFail() catch unreachable;
                                     ^

At runtime:

test.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;
}

$ zig build-exe test.zig
$ ./test
thread 17368 panic: attempt to unwrap error: UnableToReturnNumber
/home/andy/Downloads/zig/docgen_tmp/test.zig:9:5: 0x231254 in getNumberOrFail (test)
    return error.UnableToReturnNumber;
    ^
???:?:?: 0x20c682 in ??? (???)
/home/andy/Downloads/zig/docgen_tmp/test.zig:4:38: 0x229fbb in main (test)
    const number = getNumberOrFail() catch unreachable;
                                     ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x22233c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x2061ce in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x2051f6 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x205002 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(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:

test.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;
}

$ zig build-exe test.zig
$ ./test
got error: UnableToReturnNumber

Invalid Error Code

At compile-time:

test.zig

comptime {
    const err = error.AnError;
    const number = @errorToInt(err) + 10;
    const invalid_err = @intToError(number);
}

$ zig test test.zig
./docgen_tmp/test.zig:4:25: error: integer value 11 represents no error
    const invalid_err = @intToError(number);
                        ^

At runtime:

test.zig

const std = @import("std");
pub fn main() void {
    var err = error.AnError;
    var number = @errorToInt(err) + 500;
    var invalid_err = @intToError(number);
    std.debug.print("value: {}\n", .{number});
}

$ zig build-exe test.zig
$ ./test
thread 17469 panic: invalid error code
/home/andy/Downloads/zig/docgen_tmp/test.zig:6:23: 0x229fc3 in main (test)
    var invalid_err = @intToError(number);
                      ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x22234c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x2061de in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x205206 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x205012 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(process terminated by signal)

Invalid Enum Cast

At compile-time:

test.zig

const Foo = enum {
    a,
    b,
    c,
};
comptime {
    const a: u2 = 3;
    const b = @intToEnum(Foo, a);
}

$ zig test test.zig
./docgen_tmp/test.zig:8:15: error: enum 'Foo' has no tag matching integer value 3
    const b = @intToEnum(Foo, a);
              ^
./docgen_tmp/test.zig:1:13: note: 'Foo' declared here
const Foo = enum {
            ^

At runtime:

test.zig

const std = @import("std");
const Foo = enum {
    a,
    b,
    c,
};
pub fn main() void {
    var a: u2 = 3;
    var b = @intToEnum(Foo, a);
    std.debug.print("value: {s}\n", .{@tagName(b)});
}

$ zig build-exe test.zig
$ ./test
thread 17530 panic: invalid enum value
/home/andy/Downloads/zig/docgen_tmp/test.zig:11:13: 0x229ff9 in main (test)
    var b = @intToEnum(Foo, a);
            ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x2223ac in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x20623e in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x205266 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x205072 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(process terminated by signal)

Invalid Error Set Cast

At compile-time:

test.zig

const Set1 = error{
    A,
    B,
};
const Set2 = error{
    A,
    C,
};
comptime {
    _ = @errSetCast(Set2, Set1.B);
}

$ zig test test.zig
./docgen_tmp/test.zig:10:9: error: error.B not a member of error set 'Set2'
    _ = @errSetCast(Set2, Set1.B);
        ^

At runtime:

test.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 = @errSetCast(Set2, set1);
    std.debug.print("value: {}\n", .{x});
}

$ zig build-exe test.zig
$ ./test
thread 17592 panic: invalid error code
/home/andy/Downloads/zig/docgen_tmp/test.zig:15:15: 0x231256 in foo (test)
    const x = @errSetCast(Set2, set1);
              ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:12:8: 0x229fbd in main (test)
    foo(Set1.B);
       ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x22239c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x20622e in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x205256 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x205062 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(process terminated by signal)

Incorrect Pointer Alignment

At compile-time:

test.zig

comptime {
    const ptr = @intToPtr(*align(1) i32, 0x1);
    const aligned = @alignCast(4, ptr);
}

$ zig test test.zig
./docgen_tmp/test.zig:3:35: error: pointer address 0x1 is not aligned to 4 bytes
    const aligned = @alignCast(4, ptr);
                                  ^
./docgen_tmp/test.zig:3:21: note: referenced here
    const aligned = @alignCast(4, ptr);
                    ^

At runtime:

test.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, @alignCast(4, slice4));
    return int_slice[0];
}

$ zig build-exe test.zig
$ ./test
thread 17652 panic: incorrect alignment
/home/andy/Downloads/zig/docgen_tmp/test.zig:9:59: 0x2314dc in foo (test)
    const int_slice = mem.bytesAsSlice(u32, @alignCast(4, slice4));
                                                          ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:5:12: 0x22a135 in main (test)
    if (foo(bytes) != 0x11111111) return error.Wrong;
           ^
/home/andy/Downloads/zig/lib/std/start.zig:471:37: 0x2223ba in std.start.callMain (test)
            const result = root.main() catch |err| {
                                    ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x20621e in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x205246 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x205052 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(process terminated by signal)

Wrong Union Field Access

At compile-time:

test.zig

comptime {
    var f = Foo{ .int = 42 };
    f.float = 12.34;
}
const Foo = union {
    float: f32,
    int: u32,
};

$ zig test test.zig
./docgen_tmp/test.zig:3:6: error: accessing union field 'float' while field 'int' is set
    f.float = 12.34;
     ^

At runtime:

test.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});
}

$ zig build-exe test.zig
$ ./test
thread 17714 panic: access of inactive union field
/home/andy/Downloads/zig/docgen_tmp/test.zig:14:6: 0x23e9da in bar (test)
    f.float = 12.34;
     ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:10:8: 0x23773c in main (test)
    bar(&f);
       ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x22fb0c in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x21399e in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x2129c6 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x2127d2 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(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:

test.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});
}

$ zig build-exe test.zig
$ ./test
value: 1.23400001e+01

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

test.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;
}

$ zig build-exe test.zig
$ ./test
value: 1.23400001e+01

Out of Bounds Float to Integer Cast

TODO

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.zig

comptime {
    const opt_ptr: ?*i32 = null;
    const ptr = @ptrCast(*i32, opt_ptr);
}

$ zig test test.zig
./docgen_tmp/test.zig:3:17: error: null pointer casted to type '*i32'
    const ptr = @ptrCast(*i32, opt_ptr);
                ^

At runtime:

test.zig

pub fn main() void {
    var opt_ptr: ?*i32 = null;
    var ptr = @ptrCast(*i32, opt_ptr);
}

$ zig build-exe test.zig
$ ./test
thread 17846 panic: cast causes pointer to be null
/home/andy/Downloads/zig/docgen_tmp/test.zig:3:15: 0x229f10 in main (test)
    var ptr = @ptrCast(*i32, opt_ptr);
              ^
/home/andy/Downloads/zig/lib/std/start.zig:461:22: 0x2222cc in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:413:12: 0x20615e in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:332:17: 0x205186 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:245:5: 0x204f92 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(process terminated by signal)