Errors

Error Set Type

An error set is like an enum. However, each error name across the entire compilation gets assigned an unsigned integer greater than 0. You are allowed to declare the same error name more than once, and if you do, it gets assigned the same integer value.

The number of unique error values across the entire compilation should determine the size of the error set type. However right now it is hard coded to be a u16. See #768.

You can coerce an error from a subset to a superset:

test.zig

const std = @import("std");
const FileOpenError = error {
    AccessDenied,
    OutOfMemory,
    FileNotFound,
};
const AllocationError = error {
    OutOfMemory,
};
test "coerce subset to superset" {
    const err = foo(AllocationError.OutOfMemory);
    std.testing.expect(err == FileOpenError.OutOfMemory);
}
fn foo(err: AllocationError) FileOpenError {
    return err;
}

$ zig test test.zig
1/1 test "coerce subset to superset"... OK
All 1 tests passed.

But you cannot coerce an error from a superset to a subset:

test.zig

const FileOpenError = error {
    AccessDenied,
    OutOfMemory,
    FileNotFound,
};
const AllocationError = error {
    OutOfMemory,
};
test "coerce superset to subset" {
    foo(FileOpenError.OutOfMemory) catch {};
}
fn foo(err: FileOpenError) AllocationError {
    return err;
}

$ zig test test.zig
./docgen_tmp/test.zig:16:12: error: expected type 'AllocationError', found 'FileOpenError'
    return err;
           ^
./docgen_tmp/test.zig:2:5: note: 'error.AccessDenied' not a member of destination error set
    AccessDenied,
    ^
./docgen_tmp/test.zig:4:5: note: 'error.FileNotFound' not a member of destination error set
    FileNotFound,
    ^

There is a shortcut for declaring an error set with only 1 value, and then getting that value:

const err = error.FileNotFound;

This is equivalent to:

const err = (error {FileNotFound}).FileNotFound;

This becomes useful when using Inferred Error Sets.

The Global Error Set

anyerror refers to the global error set. This is the error set that contains all errors in the entire compilation unit. It is a superset of all other error sets and a subset of none of them.

You can coerce any error set to the global one, and you can explicitly cast an error of the global error set to a non-global one. This inserts a language-level assert to make sure the error value is in fact in the destination error set.

The global error set should generally be avoided because it prevents the compiler from knowing what errors are possible at compile-time. Knowing the error set at compile-time is better for generated documentation and helpful error messages, such as forgetting a possible error value in a switch.

Error Union Type

An error set type and normal type can be combined with the ! binary operator to form an error union type. You are likely to use an error union type more often than an error set type by itself.

Here is a function to parse a string into a 64-bit integer:

test.zig

const std = @import("std");
const maxInt = std.math.maxInt;
pub fn parseU64(buf: []const u8, radix: u8) !u64 {
    var x: u64 = 0;
    for (buf) |c| {
        const digit = charToDigit(c);
        if (digit >= radix) {
            return error.InvalidChar;
        }
        // x *= radix
        if (@mulWithOverflow(u64, x, radix, &x)) {
            return error.Overflow;
        }
        // x += digit
        if (@addWithOverflow(u64, x, digit, &x)) {
            return error.Overflow;
        }
    }
    return x;
}
fn charToDigit(c: u8) u8 {
    return switch (c) {
        '0' ... '9' => c - '0',
        'A' ... 'Z' => c - 'A' + 10,
        'a' ... 'z' => c - 'a' + 10,
        else => maxInt(u8),
    };
}
test "parse u64" {
    const result = try parseU64("1234", 10);
    std.testing.expect(result == 1234);
}

$ zig test test.zig
1/1 test "parse u64"... OK
All 1 tests passed.

Notice the return type is !u64. This means that the function either returns an unsigned 64 bit integer, or an error. We left off the error set to the left of the !, so the error set is inferred.

Within the function definition, you can see some return statements that return an error, and at the bottom a return statement that returns a u64. Both types coerce to anyerror!u64.

What it looks like to use this function varies depending on what you’re trying to do. One of the following:

• You want to provide a default value if it returned an error.
• If it returned an error then you want to return the same error.
• You know with complete certainty it will not return an error, so want to unconditionally unwrap it.
• You want to take a different action for each possible error.

catch

If you want to provide a default value, you can use the catch binary operator:

fn doAThing(str: []u8) void {
    const number = parseU64(str, 10) catch 13;
    // ...
}

In this code, number will be equal to the successfully parsed string, or a default value of 13. The type of the right hand side of the binary catch operator must match the unwrapped error union type, or be of type noreturn.

try

Let’s say you wanted to return the error if you got one, otherwise continue with the function logic:

fn doAThing(str: []u8) !void {
    const number = parseU64(str, 10) catch |err| return err;
    // ...
}

There is a shortcut for this. The try expression:

fn doAThing(str: []u8) !void {
    const number = try parseU64(str, 10);
    // ...
}

try evaluates an error union expression. If it is an error, it returns from the current function with the same error. Otherwise, the expression results in the unwrapped value.

Maybe you know with complete certainty that an expression will never be an error. In this case you can do this:

const number = parseU64("1234", 10) catch unreachable;

Here we know for sure that “1234” will parse successfully. So we put the unreachable value on the right hand side. unreachable generates a panic in Debug and ReleaseSafe modes and undefined behavior in ReleaseFast mode. So, while we’re debugging the application, if there was a surprise error here, the application would crash appropriately.

Finally, you may want to take a different action for every situation. For that, we combine the if and switch expression:

fn doAThing(str: []u8) void {
    if (parseU64(str, 10)) |number| {
        doSomethingWithNumber(number);
    } else |err| switch (err) {
        error.Overflow => {
            // handle overflow...
        },
        // we promise that InvalidChar won't happen (or crash in debug mode if it does)
        error.InvalidChar => unreachable,
    }
}

errdefer

The other component to error handling is defer statements. In addition to an unconditional defer, Zig has errdefer, which evaluates the deferred expression on block exit path if and only if the function returned with an error from the block.

Example:

fn createFoo(param: i32) !Foo {
    const foo = try tryToAllocateFoo();
    // now we have allocated foo. we need to free it if the function fails.
    // but we want to return it if the function succeeds.
    errdefer deallocateFoo(foo);
    const tmp_buf = allocateTmpBuffer() orelse return error.OutOfMemory;
    // tmp_buf is truly a temporary resource, and we for sure want to clean it up
    // before this block leaves scope
    defer deallocateTmpBuffer(tmp_buf);
    if (param > 1337) return error.InvalidParam;
    // here the errdefer will not run since we're returning success from the function.
    // but the defer will run!
    return foo;
}

The neat thing about this is that you get robust error handling without the verbosity and cognitive overhead of trying to make sure every exit path is covered. The deallocation code is always directly following the allocation code.

A couple of other tidbits about error handling:

• These primitives give enough expressiveness that it’s completely practical to have failing to check for an error be a compile error. If you really want to ignore the error, you can add catch unreachable and get the added benefit of crashing in Debug and ReleaseSafe modes if your assumption was wrong.
• Since Zig understands error types, it can pre-weight branches in favor of errors not occurring. Just a small optimization benefit that is not available in other languages.

See also:

• defer
• if
• switch

An error union is created with the ! binary operator. You can use compile-time reflection to access the child type of an error union:

test.zig

const expect = @import("std").testing.expect;
test "error union" {
    var foo: anyerror!i32 = undefined;
    // Coerce from child type of an error union:
    foo = 1234;
    // Coerce from an error set:
    foo = error.SomeError;
    // Use compile-time reflection to access the payload type of an error union:
    comptime expect(@typeInfo(@TypeOf(foo)).ErrorUnion.payload == i32);
    // Use compile-time reflection to access the error set type of an error union:
    comptime expect(@typeInfo(@TypeOf(foo)).ErrorUnion.error_set == anyerror);
}

$ zig test test.zig
1/1 test "error union"... OK
All 1 tests passed.

Merging Error Sets

Use the || operator to merge two error sets together. The resulting error set contains the errors of both error sets. Doc comments from the left-hand side override doc comments from the right-hand side. In this example, the doc comments for C.PathNotFound is A doc comment.

This is especially useful for functions which return different error sets depending on comptime branches. For example, the Zig standard library uses LinuxFileOpenError || WindowsFileOpenError for the error set of opening files.

test.zig

const A = error{
    NotDir,
    /// A doc comment
    PathNotFound,
};
const B = error{
    OutOfMemory,
    /// B doc comment
    PathNotFound,
};
const C = A || B;
fn foo() C!void {
    return error.NotDir;
}
test "merge error sets" {
    if (foo()) {
        @panic("unexpected");
    } else |err| switch (err) {
        error.OutOfMemory => @panic("unexpected"),
        error.PathNotFound => @panic("unexpected"),
        error.NotDir => {},
    }
}

$ zig test test.zig
1/1 test "merge error sets"... OK
All 1 tests passed.

Inferred Error Sets

Because many functions in Zig return a possible error, Zig supports inferring the error set. To infer the error set for a function, use this syntax:

test.zig

// With an inferred error set
pub fn add_inferred(comptime T: type, a: T, b: T) !T {
    var answer: T = undefined;
    return if (@addWithOverflow(T, a, b, &answer)) error.Overflow else answer;
}
// With an explicit error set
pub fn add_explicit(comptime T: type, a: T, b: T) Error!T {
    var answer: T = undefined;
    return if (@addWithOverflow(T, a, b, &answer)) error.Overflow else answer;
}
const Error = error {
    Overflow,
};
const std = @import("std");
test "inferred error set" {
    if (add_inferred(u8, 255, 1)) |_| unreachable else |err| switch (err) {
        error.Overflow => {}, // ok
    }
}

$ zig test test.zig
1/1 test "inferred error set"... OK
All 1 tests passed.

When a function has an inferred error set, that function becomes generic and thus it becomes trickier to do certain things with it, such as obtain a function pointer, or have an error set that is consistent across different build targets. Additionally, inferred error sets are incompatible with recursion.

In these situations, it is recommended to use an explicit error set. You can generally start with an empty error set and let compile errors guide you toward completing the set.

These limitations may be overcome in a future version of Zig.

Error Return Traces

Error Return Traces show all the points in the code that an error was returned to the calling function. This makes it practical to use try everywhere and then still be able to know what happened if an error ends up bubbling all the way out of your application.

test.zig

pub fn main() !void {
    try foo(12);
}
fn foo(x: i32) !void {
    if (x >= 5) {
        try bar();
    } else {
        try bang2();
    }
}
fn bar() !void {
    if (baz()) {
        try quux();
    } else |err| switch (err) {
        error.FileNotFound => try hello(),
        else => try another(),
    }
}
fn baz() !void {
    try bang1();
}
fn quux() !void {
    try bang2();
}
fn hello() !void {
    try bang2();
}
fn another() !void {
    try bang1();
}
fn bang1() !void {
    return error.FileNotFound;
}
fn bang2() !void {
    return error.PermissionDenied;
}

$ zig build-exe test.zig
$ ./test
error: PermissionDenied
/home/andy/Downloads/zig/docgen_tmp/test.zig:39:5: 0x232542 in bang1 (test)
    return error.FileNotFound;
    ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:23:5: 0x23241f in baz (test)
    try bang1();
    ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:43:5: 0x2323e2 in bang2 (test)
    return error.PermissionDenied;
    ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:31:5: 0x23250f in hello (test)
    try bang2();
    ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:17:31: 0x2323ae in bar (test)
        error.FileNotFound => try hello(),
                              ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:7:9: 0x23229c in foo (test)
        try bar();
        ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:2:5: 0x22b264 in main (test)
    try foo(12);
    ^

Look closely at this example. This is no stack trace.

You can see that the final error bubbled up was PermissionDenied, but the original error that started this whole thing was FileNotFound. In the bar function, the code handles the original error code, and then returns another one, from the switch statement. Error Return Traces make this clear, whereas a stack trace would look like this:

test.zig

pub fn main() void {
    foo(12);
}
fn foo(x: i32) void {
    if (x >= 5) {
        bar();
    } else {
        bang2();
    }
}
fn bar() void {
    if (baz()) {
        quux();
    } else {
        hello();
    }
}
fn baz() bool {
    return bang1();
}
fn quux() void {
    bang2();
}
fn hello() void {
    bang2();
}
fn bang1() bool {
    return false;
}
fn bang2() void {
    @panic("PermissionDenied");
}

$ zig build-exe test.zig
$ ./test
PermissionDenied
/home/andy/Downloads/zig/docgen_tmp/test.zig:38:5: 0x233bd6 in bang2 (test)
    @panic("PermissionDenied");
    ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:30:10: 0x234278 in hello (test)
    bang2();
         ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:17:14: 0x233bba in bar (test)
        hello();
             ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:7:12: 0x232035 in foo (test)
        bar();
           ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:2:8: 0x22b06d in main (test)
    foo(12);
       ^
/home/andy/Downloads/zig/lib/std/start.zig:324:22: 0x204caf in std.start.posixCallMainAndExit (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:162:5: 0x204a82 in std.start._start (test)
    @call(.{ .modifier = .never_inline }, posixCallMainAndExit, .{});
    ^
(process terminated by signal)

Here, the stack trace does not explain how the control flow in bar got to the hello() call. One would have to open a debugger or further instrument the application in order to find out. The error return trace, on the other hand, shows exactly how the error bubbled up.

This debugging feature makes it easier to iterate quickly on code that robustly handles all error conditions. This means that Zig developers will naturally find themselves writing correct, robust code in order to increase their development pace.

Error Return Traces are enabled by default in Debug and ReleaseSafe builds and disabled by default in ReleaseFast and ReleaseSmall builds.

There are a few ways to activate this error return tracing feature:

• Return an error from main
• An error makes its way to catch unreachable and you have not overridden the default panic handler
• Use errorReturnTrace to access the current return trace. You can use std.debug.dumpStackTrace to print it. This function returns comptime-known null when building without error return tracing support.

Implementation Details

To analyze performance cost, there are two cases:

• when no errors are returned
• when returning errors

For the case when no errors are returned, the cost is a single memory write operation, only in the first non-failable function in the call graph that calls a failable function, i.e. when a function returning void calls a function returning error. This is to initialize this struct in the stack memory:

pub const StackTrace = struct {
    index: usize,
    instruction_addresses: [N]usize,
};

Here, N is the maximum function call depth as determined by call graph analysis. Recursion is ignored and counts for 2.

A pointer to StackTrace is passed as a secret parameter to every function that can return an error, but it’s always the first parameter, so it can likely sit in a register and stay there.

That’s it for the path when no errors occur. It’s practically free in terms of performance.

When generating the code for a function that returns an error, just before the return statement (only for the return statements that return errors), Zig generates a call to this function:

// marked as "no-inline" in LLVM IR
fn __zig_return_error(stack_trace: *StackTrace) void {
    stack_trace.instruction_addresses[stack_trace.index] = @returnAddress();
    stack_trace.index = (stack_trace.index + 1) % N;
}

The cost is 2 math operations plus some memory reads and writes. The memory accessed is constrained and should remain cached for the duration of the error return bubbling.

As for code size cost, 1 function call before a return statement is no big deal. Even so, I have a plan to make the call to __zig_return_error a tail call, which brings the code size cost down to actually zero. What is a return statement in code without error return tracing can become a jump instruction in code with error return tracing.