Fehler - A comprehensive error reporting system for Zig

ciathefed · August 29, 2025, 2:28pm

Inspired by miette and rustc for Rust and Zig’s own compiler diagnostics, fehler gives you:

Colorful, source-annotated diagnostics
File/line/column tracking
Help messages and fluent API
Built-in severity levels and labels
Clean allocator-safe design

Example:

Works great for compilers, preprocessors, and any tool that needs human-readable diagnostics.

GitHub: github.com/ciathefed/fehler

Feedback, bug reports, and suggestions welcome. I’d love to hear what you think or what’s missing.

matklad · August 29, 2025, 2:53pm

If this try fails:

github.com/ciathefed/fehler

src/root.zig

49c36aec9


      
              return reporter;
          }
          
          /// Adds a source file to the reporter for later reference in diagnostics.
          /// The content is duplicated and owned by the reporter.
          pub fn addSource(self: *ErrorReporter, filename: []const u8, content: []const u8) !void {
              if (self.sources.get(filename)) |old_content| {
                  self.allocator.free(old_content);
              }
          
              const owned_content = try self.allocator.dupe(u8, content);
              try self.sources.put(filename, owned_content);
          }
          
          /// Reports a single diagnostic to stdout with color formatting.
          /// If the diagnostic has a range and the source file is available,
          /// displays a source code snippet with the error range highlighted.
          pub fn report(self: *ErrorReporter, diagnostic: Diagnostic) void {
              switch (self.format) {
                  .fehler => self.printFehler(diagnostic),
                  .gcc => self.printGcc(diagnostic),

then we end up removing existing source form the sources map without replacement.

If this try fails:

github.com/ciathefed/fehler

src/root.zig

49c36aec9


      
          }
          
          /// Adds a source file to the reporter for later reference in diagnostics.
          /// The content is duplicated and owned by the reporter.
          pub fn addSource(self: *ErrorReporter, filename: []const u8, content: []const u8) !void {
              if (self.sources.get(filename)) |old_content| {
                  self.allocator.free(old_content);
              }
          
              const owned_content = try self.allocator.dupe(u8, content);
              try self.sources.put(filename, owned_content);
          }
          
          /// Reports a single diagnostic to stdout with color formatting.
          /// If the diagnostic has a range and the source file is available,
          /// displays a source code snippet with the error range highlighted.
          pub fn report(self: *ErrorReporter, diagnostic: Diagnostic) void {
              switch (self.format) {
                  .fehler => self.printFehler(diagnostic),
                  .gcc => self.printGcc(diagnostic),
                  .msvc => self.printMsvc(diagnostic),

we end up additionally leaking owned_content.

You want to Reserve First.

ciathefed · August 29, 2025, 3:25pm

from what i’ve gathered from Reserve First, i think i’ve came up with a solution. before i push the change, some feedback would be appreciated.

pub fn addSource(self: *ErrorReporter, filename: []const u8, content: []const u8) !void {
    try self.sources.ensureTotalCapacity(self.sources.count() + 1);
    const owned_content = try self.allocator.dupe(u8, content);
    errdefer comptime unreachable;

    const gop = self.sources.getOrPutAssumeCapacity(filename);
    if (gop.found_existing) {
        self.allocator.free(gop.value_ptr.*);
    }
    gop.value_ptr.* = owned_content;
}

matklad · August 29, 2025, 3:31pm

Yup, this is perfect! I also like using gop to avoid redundant hashmap lookup!

matklad · August 29, 2025, 3:34pm

Ah, wait, I think there’s also .ensureExtraCapcity(1), which might be a bit more convenient here!

KilianHanich · August 29, 2025, 3:48pm

It’s called ensureUnusedCapacity.

tsdtas · September 2, 2025, 10:31am

Just wanted to say, that article has significantly changed how I approach error handling in Zig for the better. Thank you for writing it.

matklad · September 2, 2025, 10:49am

Thank andrewrk, I just wrote down his Zulip comment :

yep that reserve capacity should go above the other try

or an errdefer needs to undo the hash map addition. but I usually prefer the reserve pattern

This was new to me as well!