Returning Errors from Functions
Make failure explicit in signatures.
Returning Errors from Functions is a free Zig Academy lesson on CoddyKit — lesson 2 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.
Failure in the Signature
When a function can fail, say so in its return type. An error union like ParseError!u32 warns every caller up front.
fn parse(s: []const u8) ParseError!u32 {
// ...
}Return the Success Value
On the happy path you just return the payload as normal. Zig wraps that plain value into the success side of the union for you.
return 42;Return an Error Instead
To fail, return one of your errors in the same spot. The single return statement decides which side of the union you produce.
if (s.len == 0) return error.Empty;One Return, Two Outcomes
A function with an error union can return a value in one branch and an error in another. Both satisfy the declared type.
if (ok) return value;
return error.Failed;Void Plus Errors
A function that does work but yields no value can still fail. Use !void so it returns nothing on success or an error on failure.
fn save() !void {
// ...
}Errors Bubble at the Call Site
When you call a fallible function, you receive an error union too. You cannot ignore it; the compiler makes you handle it.
const n = parse(input);Capture Errors with if
An if can split the union: capture the value in the main branch and the error after else, naming each with a pipe.
if (parse(input)) |n| {
use(n);
} else |err| {
report(err);
}Name the Error Set Precisely
Listing the exact set before ! keeps your contract honest. Callers learn the full list of failures without reading the body.
fn open(p: []const u8) FileError!File {}Errors Cross Function Boundaries
An error returned deep inside your code travels outward only when each function in the chain declares it can fail too.
Make Failure Explicit
This is the heart of Zig error handling: failure is never hidden. The signature is a promise about what can go wrong.
Compiler Has Your Back
Forget to handle a returned error and the build fails. Zig refuses to let a possible failure silently slip through.
Quick Check
A function does work but returns no useful value, yet it might fail. What return type fits?
Recap
You declared fallible functions with !T, returned values or errors from one return, and saw the compiler force callers to handle them. ✅
Frequently asked questions
Is the “Returning Errors from Functions” lesson free?
Yes — the full text of “Returning Errors from Functions” 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 “Returning Errors from Functions”?
Make failure explicit in signatures. 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 2 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Returning Errors from Functions” 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
- Error Sets and the !T Union
- Returning Errors from Functions
- Propagate Failures with try
- Inferred Error Sets