Wrapping and Re-throwing Errors
Add context as errors travel up.
Wrapping and Re-throwing Errors is a free Zig Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Zig Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Errors Travel Upward
When a function cannot handle a failure itself, it passes the error to its caller. Along the way you can adjust or re-throw it.
Re-throw with try
The simplest re-throw is try. It forwards the original error unchanged to your caller, so the same value keeps bubbling up.
const data = try readFile(path);Catch Then Return
To translate an error, catch it and return a different one. This swaps a low-level error for one that fits your own API.
const f = open(path) catch return error.ConfigMissing;Map Errors with switch
Combine catch with a switch to map each underlying error to a clearer one, while passing the rest through unchanged.
parse(s) catch |e| switch (e) {
error.Empty => return error.NoInput,
else => return e,
};Zig Has No Stack Traces by Value
An error in Zig is just a tag, not an object holding context. To add detail you re-throw a more descriptive error of your own.
Attach Context Separately
Since the error tag carries no message, log the details where the failure happens, then return the higher-level error to the caller.
open(path) catch |e| {
std.log.err("open {s}: {}", .{ path, e });
return error.LoadFailed;
};Widen the Error Set
If you return a new error, your function's error set must include it. An inferred !T set grows to cover everything you return.
fn load() !Config {
return open(".cfg") catch error.LoadFailed;
}Preserve or Replace
Decide per layer: forward the exact error with try, or replace it with one that makes more sense to your caller. Both are valid.
Keep Boundaries Clean
At a module boundary, map internal errors to a small public set. Callers then depend on stable names, not your internals.
Pair with errdefer
When you re-throw, any errdefer in scope still fires first. So you can rollback resources and translate the error in one path.
Meaningful Failures
Wrapping errors turns a raw cause into a message that fits your domain. The caller sees a clear error instead of an internal detail.
Quick Check
You want to replace a low-level error.NotFound with your own error.ConfigMissing for the caller. Which works?
Recap
You re-threw errors with try, mapped them via catch and switch, logged context, and widened error sets to keep failures meaningful. ✅
Frequently asked questions
Is the “Wrapping and Re-throwing Errors” lesson free?
Yes — the full text of “Wrapping and Re-throwing Errors” is free to read here on the web, and the Zig Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Zig Academy course, upgrade to CoddyKit PRO.
What will I learn in “Wrapping and Re-throwing Errors”?
Add context as errors travel up. You practise Zig Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Zig Academy?
No prior experience is required. Zig Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Wrapping and Re-throwing Errors” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Zig Academy lesson?
Yes. Every Zig Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Recover with catch
- Switch on Specific Errors
- errdefer for Failure Cleanup
- Wrapping and Re-throwing Errors