Diagnostics Factory

matklad 02/16/26, 12:00 AM Tools

Summary

该文章介绍了在Zig中使用诊断工厂模式来管理错误报告，避免预先定义错误类型，而是提供一组构造函数来生成错误信息，并展示了在TigerBeetle项目中的实际应用。

<header> <h1>Diagnostics Factory</h1> <time class="meta" datetime="2026-02-16">Feb 16, 2026</time> </header> In <a href="https://matklad.github.io/2025/11/06/error-codes-for-control-flow.html">Error Codes For Control Flow</a>, I explained that Zig’s strongly-typed error codes solve the “handling” half of error management, leaving “reporting” to the users. Today, I want to describe my personal default approach to the reporting problem, that is, showing the user a useful error message. The approach is best described in the negative: avoid thinking about error payloads, and what the type of error should be. Instead, provide a set of functions for constructing errors. To give a concrete example, in TigerBeetle’s <a href="https://github.com/tigerbeetle/tigerbeetle/blob/0.16.73/src/tidy.zig#L54-L188"><code>tidy.zig</code></a> (a project-specific linting script, another useful meta-pattern), we define errors as follows: <figure class="code-block"> <pre><code>const Errors = struct { pub fn add_long_line( errors: *Errors, file: SourceFile, line_index: usize, ) void { ... } pub fn add_banned( errors: *Errors, file: SourceFile, offset: usize, banned_item: []const u8, replacement: []const u8, ) void { ... } pub fn add_dead_declaration(...) void { ... } ... };</code></pre> </figure> and the call-site looks like this: <figure class="code-block"> <pre><code>fn tidy_file(file: SourceFile, errors: *Errors) void { // ... var line_index: usize = 0; while (lines.next()) |line| : (line_index += 1) { const line_length = line_length(line); if (line_length > 100 and !contains_url(line)) { errors.add_long_line(file, line_index); } } }</code></pre> </figure> In this case, I collect multiple errors so I don’t return right away. Fail fast would look like this: <figure class="code-block"> <pre><code>errors.add_long_line(file, line_index); return error.Tidy;</code></pre> </figure> Note that the error code is intentionally independent of the specific error produced. <hr> Some interesting properties of the solution: <ul> <li> The error representation is a set of constructor functions, the calling code doesn’t care what actually happens inside. This is why the error factory is my default solution — I don’t have to figure out up-front what I’ll do with the errors, and I can change my mind later. </li> <li> There’s a natural place to convert information from the form available at the place where we emit the error to a form useful for the user. In <code>add_banned</code> above, the caller passes in a absolute offset in a file, and it is resolved to line number and column inside (tip: use <code>line_index</code> for 0-based internal indexes, and <code>line_number</code> for user-visible 1-based ones). Contrast this with a traditional error as sum-type approach, where there’s a sharp syntactic discontinuity between constructing a variant directly and calling a helper function. </li> <li> This syntactic uniformity in turn allows easily grepping for all error locations: <code>rg 'errors.add_'</code>. </li> <li> Similarly, there’s one central place that enumerates all possible errors (which is either a benefit or a drawback). </li> </ul> A less trivial property is that this structure enables polymorphism. In fact, in the <code>tidy.zig</code> code, there are two different representations of errors. When running the script, errors are directly emitted to stderr. But when testing it, errors are collected into an in-memory buffer: <figure class="code-block"> <pre><code>pub fn add_banned( errors: *Errors, file: SourceFile, offset: usize, banned_item: []const u8, replacement: []const u8, ) void { errors.emit( "{s}:{d}: error: {s} is banned, use {s}\n", .{ file.path, file.line_number(offset), banned_item, replacement, }, ); } fn emit( errors: *Errors, comptime fmt: []const u8, args: anytype, ) void { comptime assert(fmt[fmt.len - 1] == '\n'); errors.count += 1; if (errors.captured) |*captured| { captured.writer(errors.gpa).print(fmt, args) catch @panic("OOM"); } else { std.debug.print(fmt, args); } }</code></pre> </figure> There isn’t a giant <code>union(enum)</code> of all errors, because it’s not needed for the present use-case. This pattern can be further extended to a full-fledged diagnostics framework with error builders, spans, ANSI colors and such, but that is tangential to the main idea here: even when “programming in the small”, it might be a good idea to avoid constructing enums directly, and mandate an intermediate function call. <hr> Two more meta observations here: First, the entire pattern is of course the expression of duality between a sum of two types and a product of two functions (the visitor pattern) <figure class="code-block"> <pre><code>fn foo() -> Result<T, E>; fn bar(ok: impl FnOnce(T), err: impl FnOnce(E));</code></pre> </figure> <figure class="code-block"> <pre><code>enum Result<T, E> { Ok(T), Err(E), } trait Result<T, E> { fn ok(self, T); fn err(self, E); }</code></pre> </figure> Second, every abstraction is a thin film separating two large bodies of code. Any interface has two sides, the familiar one presented to the user, and the other, hidden one, presented to the implementor. Often, default language machinery pushes you towards using the same construct for both but that can be suboptimal. It’s natural for the user and the provider of the abstraction to disagree on the optimal interface, and to evolve independently. Using a single big enum for errors couples error emitting and error reporting code, as they have to meet in the middle. In contrast, the factory solution is optimal for producer (they literally just pass whatever they already have on hand, without any extra massaging of data), and is flexible for consumer(s).

Original Article

View Cached Full Text

Cached at: 05/16/26, 03:34 AM

# Diagnostics Factory Source: [https://matklad.github.io/2026/02/16/diagnostics-factory.html](https://matklad.github.io/2026/02/16/diagnostics-factory.html) Feb 16, 2026In[*Error Codes For Control Flow*](https://matklad.github.io/2025/11/06/error-codes-for-control-flow.html),I explained that Zig’s strongly\-typed error codes solve the “handling” half of error management, leaving “reporting” to the users\. Today, I want to describe my personal default approach to the reporting problem, that is, showing the user a useful error message\. The approach is best described in the negative:*avoid*thinking about error payloads, and what the type of error should be\. Instead, provide a set of functions for constructing errors\. To give a concrete example, in TigerBeetle’s[`tidy\.zig`](https://github.com/tigerbeetle/tigerbeetle/blob/0.16.73/src/tidy.zig#L54-L188)\(a project\-specific linting script, another useful meta\-pattern\), we define errors as follows: ``` const Errors = struct { pub fn add_long_line( errors: *Errors, file: SourceFile, line_index: usize, ) void { ... } pub fn add_banned( errors: *Errors, file: SourceFile, offset: usize, banned_item: []const u8, replacement: []const u8, ) void { ... } pub fn add_dead_declaration(...) void { ... } ... }; ``` and the call\-site looks like this: ``` fn tidy_file(file: SourceFile, errors: *Errors) void { // ... var line_index: usize = 0; while (lines.next()) |line| : (line_index += 1) { const line_length = line_length(line); if (line_length > 100 and !contains_url(line)) { errors.add_long_line(file, line_index); } } } ``` In this case, I collect multiple errors so I don’t return right away\. Fail fast would look like this: ``` errors.add_long_line(file, line_index); return error.Tidy; ``` Note that the error code is intentionally independent of the specific error produced\. --- Some interesting properties of the solution: - The error representation is a set of constructor functions, the calling code doesn’t care what*actually*happens inside\. This is why the error factory is my*default*solution — I don’t have to figure out up\-front what I’ll do with the errors, and I can change my mind later\. - There’s a natural place to convert information from the form available at the place where we emit the error to a form useful for the user\. In`add\_banned`above, the caller passes in a absolute offset in a file, and it is resolved to line number and column inside \(tip: use`line\_index`for 0\-based internal indexes, and`line\_number`for user\-visible 1\-based ones\)\. Contrast this with a traditional error as sum\-type approach, where there’s a sharp syntactic discontinuity between constructing a variant directly and calling a helper function\. - This syntactic uniformity in turn allows easily grepping for all error locations:`rg 'errors\.add\_'`\. - Similarly, there’s one central place that enumerates all possible errors \(which is either a benefit or a drawback\)\. A less trivial property is that this structure enables polymorphism\. In fact, in the`tidy\.zig`code, there are two different representations of errors\. When running the script, errors are directly emitted to stderr\. But when testing it, errors are collected into an in\-memory buffer: ``` pub fn add_banned( errors: *Errors, file: SourceFile, offset: usize, banned_item: []const u8, replacement: []const u8, ) void { errors.emit( "{s}:{d}: error: {s} is banned, use {s}\n", .{ file.path, file.line_number(offset), banned_item, replacement, }, ); } fn emit( errors: *Errors, comptime fmt: []const u8, args: anytype, ) void { comptime assert(fmt[fmt.len - 1] == '\n'); errors.count += 1; if (errors.captured) |*captured| { captured.writer(errors.gpa).print(fmt, args) catch @panic("OOM"); } else { std.debug.print(fmt, args); } } ``` There isn’t a giant`union\(enum\)`of all errors, because it’s not needed for the present use\-case\. This pattern can be further extended to a full\-fledged diagnostics framework with error builders, spans, ANSI colors and such, but that is tangential to the main idea here: even when “programming in the small”, it might be a good idea to avoid constructing enums directly, and mandate an intermediate function call\. --- Two more meta observations here: *First*, the entire pattern is of course the expression of duality between a sum of two types and a product of two functions \(the visitor pattern\) ``` fn foo() -> Result<T, E>; fn bar(ok: impl FnOnce(T), err: impl FnOnce(E)); ``` ``` enum Result<T, E> { Ok(T), Err(E), } trait Result<T, E> { fn ok(self, T); fn err(self, E); } ``` *Second*, every abstraction is a thin film separating two large bodies of code\. Any interface has two sides, the familiar one presented to the user, and the other, hidden one, presented to the implementor\. Often, default language machinery pushes you towards using the same construct for both but that can be suboptimal\. It’s natural for the user and the provider of the abstraction to disagree on the optimal interface, and to evolve independently\. Using a single big enum for errors couples error emitting and error reporting code, as they have to meet in the middle\. In contrast, the factory solution is optimal for producer \(they literally just pass whatever they already have on hand, without any extra massaging of data\), and is flexible for consumer\(s\)\.

Diagnostics Factory

Similar Articles

Minimal Viable Zig Error Contexts

You Must Fix Your Asserts

Agent failure clusters changed how I think about debugging

@thinkszyg: https://x.com/thinkszyg/status/2066837941477920993

Submit Feedback

Similar Articles

@0xKingsKuan: Auto-Fix Bugs, Observability Tool! How frustrating was managing production systems before? Logs, traces, metrics everywhere, critical errors drowned in noise. When something went wrong, you had to manually dig through logs, guess the call chain, spend ages troubleshooting without finding the root cause, let alone fixing it automatically. Now, superloglabs directly...

Minimal Viable Zig Error Contexts

Agent failure clusters changed how I think about debugging

@thinkszyg: https://x.com/thinkszyg/status/2066837941477920993