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:

coercing_subset_to_superset.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);
    try std.testing.expect(err == FileOpenError.OutOfMemory);
}
fn foo(err: AllocationError) FileOpenError {
    return err;
}

Shell

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

Shell

$ 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:

test.zig

const err = error.FileNotFound;

This is equivalent to:

test.zig

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:

error_union_parsing_u64.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);
    try std.testing.expect(result == 1234);
}

Shell

$ zig test error_union_parsing_u64.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:

test.zig

const parseU64 = @import("error_union_parsing_u64.zig").parseU64;
fn doAThing(str: []u8) void {
    const number = parseU64(str, 10) catch 13;
    _ = number; // ...
}

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:

test.zig

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

There is a shortcut for this. The try expression:

test.zig

const parseU64 = @import("error_union_parsing_u64.zig").parseU64;
fn doAThing(str: []u8) !void {
    const number = try parseU64(str, 10);
    _ = number; // ...
}

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:

handle_all_error_scenarios.zig

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:

errdefer_example.zig

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_error_union.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 try expect(@typeInfo(@TypeOf(foo)).ErrorUnion.payload == i32);
    // Use compile-time reflection to access the error set type of an error union:
    comptime try expect(@typeInfo(@TypeOf(foo)).ErrorUnion.error_set == anyerror);
}

Shell

$ zig test test_error_union.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_merging_error_sets.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 => {},
    }
}

Shell

$ zig test test_merging_error_sets.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, prepend the ! operator to the function’s return type, like !T:

inferred_error_sets.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
    }
}

Shell

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

Shell

$ zig build-exe test.zig
$ ./test
error: PermissionDenied
/home/andy/Downloads/zig/docgen_tmp/test.zig:39:5: 0x234a02 in bang1 (test)
    return error.FileNotFound;
    ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:23:5: 0x2348df in baz (test)
    try bang1();
    ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:43:5: 0x2348a2 in bang2 (test)
    return error.PermissionDenied;
    ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:31:5: 0x2349cf in hello (test)
    try bang2();
    ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:17:31: 0x23486e in bar (test)
        error.FileNotFound => try hello(),
                              ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:7:9: 0x23475c in foo (test)
        try bar();
        ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:2:5: 0x22d054 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");
}

Shell

$ zig build-exe test.zig
$ ./test
thread 794855 panic: PermissionDenied
/home/andy/Downloads/zig/docgen_tmp/test.zig:38:5: 0x235876 in bang2 (test)
    @panic("PermissionDenied");
    ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:30:10: 0x235fc8 in hello (test)
    bang2();
         ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:17:14: 0x23585a in bar (test)
        hello();
             ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:7:12: 0x2344d5 in foo (test)
        bar();
           ^
/home/andy/Downloads/zig/docgen_tmp/test.zig:2:8: 0x22ce3d in main (test)
    foo(12);
       ^
/home/andy/Downloads/zig/lib/std/start.zig:543:22: 0x225bcc in std.start.callMain (test)
            root.main();
                     ^
/home/andy/Downloads/zig/lib/std/start.zig:495:12: 0x206fce in std.start.callMainWithArgs (test)
    return @call(.{ .modifier = .always_inline }, callMain, .{});
           ^
/home/andy/Downloads/zig/lib/std/start.zig:409:17: 0x206066 in std.start.posixCallMainAndExit (test)
    std.os.exit(@call(.{ .modifier = .always_inline }, callMainWithArgs, .{ argc, argv, envp }));
                ^
/home/andy/Downloads/zig/lib/std/start.zig:322:5: 0x205e72 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:

stack_trace_struct.zig

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:

zig_return_error_fn.zig

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