I see potential in that. A world where error sets are just regular unions, but given all the syntax-level amenities of today's errors.

// a regular-ass type
const InvalidChar = struct {
    pos: usize,
};

// an error set containing different types
const ParseError = error {
    InvalidChar: InvalidChar,
    Overflow, // void
};

// merge like ya would today
const Error = ParseError || error{OutOfMemory};

fn f() void {
    parse(something) catch |err| switch (err) {
        .InvalidChar => |e| warn("bad character at {}", e.pos),
        .Overflow => warn("overflow"),
        .OutOfMemory => warn("out of memory"),
    };
}

Taking it further, perhaps all today's good stuff about errors could be applied to any type, not just unions. Maybe the error keyword "taints" a type as an error type. (Although, making errors non-unions would probably have too many effects on the language.)

const SomeError1 = error struct {
    val: usize,
    reason: []const u8,
};

const SomeError2 = error union(enum) {
    OutOfOrder,
    OutOfBounds,
    OutOfIdeas,
};

// today's, which is sugar for above
const SomeError3 = error {
    ResourceExhausted,
    DeadlineExceeded,
};

Because you could now "bloat" an error set with types of larger size, this might affect how strongly use of the global error set is discouraged.

I remember seeing this proposed before but I can't find the issue for it. Maybe it was only on IRC?

Thank you @CurtisFenner for a well written proposal

This is just a tagged union.

And as they seem so useful, maybe we can add anonymous structs, so we can just use tagged unions instead of multiple return values.

Don't worry about the optimizations here. The compiler can handle that.

There's a previous issue here #572 (just for the record)

because errors are assigned a unique value, how about allowing for tagged unions to use errors as the tag value? this would avoid adding new syntax to language and making this feature consistent with other constructs in the language. this tangentially relies on #1945.

/// stolen from above

const ParseError = union(error) {
    InvalidChar: usize,
    Overflow, // equivalent to `Overflow: void`
};

pub fn parseU64(buf: []const u8, radix: u8) ParseError!u64 {
    // ......
        if (digit >= radix) {
            return error{ .InvalidChar = index };
        }
    // ......
}

test "parseU64" {
	if (parseU64(str, 10)) |number| {
		// ......
	} else |err| switch (err) {
		error.Overflow => {
			// ......
		},
		error.InvalidChar => |index| {
			// ......
		}
	}
}

Agreeing with @emoki I'd like some syntactic sugar for multiple arguments to an error switch, if the type is defined in the same tagged union:

/// stolen from above

const ParseError = union(error) {
    InvalidChar: InvalidCharStruct,
    Overflow, // equivalent to `Overflow: void`

    pub const InvalidCharStruct = {
        i: usize,
        o: bool,
    }
};

pub fn parseU64(buf: []const u8, radix: u8) ParseError!u64 {
    // ......
        if (digit >= radix) {
            return error{ .InvalidChar = .InvalidCharStruct{index, false} };
        }
    // ......
}

test "parseU64" {
	if (parseU64(str, 10)) |number| {
		// ......
	} else |err| switch (err) {
		error.Overflow => {
			// ......
		},
		error.InvalidChar => |index, boolish| {
			// ......
		}
	}
}

I think what @emekoi suggested is excellent, as it removes the need for extra syntax and sidesteps the issues of increasing the size of anyerror and dealing with error names assigned different types, while still enabling the core idea here!

return error{ .InvalidChar = index };

I assume this should be:

return ParseError{ .InvalidChar = index };

Otherwise I love the idea!

that's what i wasn't sure about. would you still have to explicitly name the error even when using an inferred error set? or would you just use error as you normally would with an inferred error set?

Not a proposal, but something possible currently: here's a variation on OP's "Workaround 2" (the out parameter). A struct member instead of an "out" parameter. It's still not perfect, but this or Workaround 2 is still the most flexible as they make it possible to allocate memory for the error value (e.g. a formatted error message).

const Thing = struct {
    const ErrorInfo = struct {
        message: []u8,
    };

    error_info: ?ErrorInfo,

    // `allocator` could also be a parameter of an init function
    fn doSomething(self: *Thing, allocator: ...) !void {
        if (bad thing 1) {
            self.error_info = ErrorInfo {
                .message = try ...allocate a string...,
            };
            return error.ThingError;
        } else if (bad thing 2) {
            self.error_info = ErrorInfo {
                .message = try ...allocate a different string...,
            };
            return error.ThingError;
        } else {
            // happy
        }
    }
};

fn caller() void {
    var thing = Thing.init();
    defer thing.deinit(); // free allocated stuff in error_info if present

    thing.doSomething(some_allocator) catch |err| {
        switch (err) { 
            error.ThingError => {
                // this `.?` is the smelliest part of this idea
                std.debug.warn("error: {}\n", thing.error_info.?.message);
            },
            else => {
                // e.g. an OOM error from when we tried to alloc for the error message
                std.debug.warn("some other error\n");
            },
        }
        return;
    }

    std.debug.warn("success\n");
}

This might be a solution for std InStream and OutStream which currently have that annoying generic error parameter?

Also, for parsers and line numbers specifically, you don't need to include the line number in the error value itself. Just maintain it in a struct member and the caller can pull it out when catching. If these struct members aren't exclusive to failed states, then there's no smell at all here.

const Parser = struct {
    ...
    line_index: usize,

    parse(self: *Parser) !?Token {
        // continually update line_index, return a regular zig error if something goes wrong
    }
};

I like @emekoi's suggestion here, but I'll note that I'd like to be able to have parseU64 return !u64 and have the error type inferred, just as we do now, and still be able to do
return error{ .InvalidIndex = index };.

I just started with Zig and as far as I can see now, the error handling is absolutely perfect and extremely elegant.

(I tried Rust for a while, where error handling is insanely complicated and hardly usable, in my opinion).

For more complicated error handling, where feedback (which can be a lot) is needed, maybe it is better to leave this to the application or library programmers to handle in a creative way.

Perhaps liberror can be a source of inspiration?
callee sets an error string, caller can decide to simply ignore it

it's one alternative to additionally returning an arbitrary type - just let the callee do the heavy lifting of setting errstr

plan9 uses error strings in its C library

Error codes are for control flow.

I agree that error codes are good for control flow, but it is super common to not care what the actual error was until much higher in the stack, and there is no idiomatic way to attach that state.

For example, consider this API:

fn persist(msg: []u8)  void! ;

Which will save the message in a buffer and write it once the buffer is full to a file with the current date as the name.
We run into an error saving the file, and we want to both show the user the error (error.FileAlreadyExists) and what the filename is.

There is no idiomatic way to do that, which is problematic.

I've discovered this pattern that I use when I both want to have error control flow (i.e. trigger errdefers) but would also like a "side-channel" for extra error information. Consider this example,

foo() catch {
    std.log.err("foo failed", .{});
};

We want to add a side-channel to foo. The general pattern is to define a FooError type that will house this side-channel data; using it looks like this:

var err: FooError = undefined;
foo(&err) catch {
    std.log.info("foo failed with {}", .{err});
};

FooError gives you a place to answer questions about how this side-channel data should be managed. Does the data need to be freed? Add a deinit function. Do you want print the error? Add a format function. Do you still want to support other zig error codes that don't populate this FooError side-channel? Reserve a special zig error code (probably error.Foo in this case) that indicates the side-channel is initialized. Here's a more comprehensive example showing the sorts of things you can do:

var err: FooError = undefined;
const result = foo(args..., &err) catch |err| switch (err) {
    error.Foo => {
        // we know err is initialized because we got error.Foo
        defer err.deinit(); // the err could have a deinit function to cleanup resources
        std.log.info("err is {}", .{err}); // the error could have a format function for printing
    },
    // if the error wasn't error.Foo, then err wouldn't be populated
    else => |e| return e,
};

And here's an example of what foo and FooError can look like:

// TIP: sometimes it's useful to make this a union(enum) type
const FooError = struct {
    side_channel_data: SideChannelData,

    // you could define a deinit function here if you have resources to clean up
    pub fn deinit(self: *FooError) void { ... }

    // the set function allows the `foo` implementation to both set the error and return
    // the proper zig error code in 1 expression
    pub fn set(self: *FooError, val: FooError) error{Foo} {
        self.* = val;
        return error.Foo;
    }
    // sometimes you might want multiple set* functions

    // if this is a more general kind of "Error" shared multiple functions, you
    // might want to defined a format function
    pub fn format(
        self: FooError ,
        comptime fmt: []const u8,
        options: std.fmt.FormatOptions,
        writer: anytype,
    ) !void {
        try writer.print(...);
    }
}

fn foo(args..., err: *FooError) !ReturnValue {
    if (something_failed) {
        // this `set` function will initialize `err` and return error.Foo
        return err.set(my_side_channel_info);
    }

    try bar(); // still ok to use 'try' with other functions
    try foo2(err); // we pass `err` to foo2 which could also return error.Foo
}

@ayende, In your example with the persist message there are some unanswered questions, such as where this filename with the date in it is stored? Are you using an allocator, or maybe it's in a global with a fixed max size? When you return the filename should the caller free it or not? We can use this pattern to answer those questions, and here's one way that could look:

const std = @import("std");

pub fn main() void {
    var err: PersistError = undefined;
    persist("my message", &err) catch {
        std.log.err("persist failed trying to write file '{s}'", .{err.getFilename()});
    };
}


pub const PersistError = struct {
    filename_buf: [200]u8,
    filename_len: usize,
    pub fn getFilename(self: *PersistError) []const u8 {
        return self.filename_buf[0..self.filename_len];
    }

    pub fn setFilename(self: *PersistError, filename: []const u8) error{PersistError} {
        self.filename_len = @min(self.filename_buf.len, filename.len);
        @memcpy(self.filename_buf[0..self.filename_len], filename);
        return error.PersistError;
    }
};
pub fn persist(msg: []const u8, err: *PersistError) error{PersistError}!void {
    _ = msg;
    const something_failed = true;
    if (something_failed) {
        return err.setFilename("my-filename-with-the-date-in-it");
    }
}

Here's a couple real-world examples:

direct2d-zig: https://github.com/marler8997/direct2d-zig/blob/6c6597a3a80203ee144bd97efc269e33c0653864/ddui.zig#L134
zware: https://github.com/malcolmstill/zware/blob/3ad3f4e10bafba1d927847720aacad78f690cec6/src/error.zig

I ended up doing something like that, sure. But the key point isn't that this is possible.
The issue is what would be the idiomatic manner to do this.

there isn't one and that's part of the freedom of Zig. unless you limit error return values to only be primitives then you have to worry about the allocation strategy of the error return and Zig is intentionally not prescriptive about that in its design.

I find myself writing a lot of this:

var foo_error_data: FooErr = undefined;
foo(&foo_error_data) catch |err| {
    error_data = .{.foo = foo_error_data};
    return err;
};

var bar_error_data: BarErr = undefined;
bar(&bar_error_data) catch |err| {
    error_data = .{.bar = bar_error_data};
    return err;
};

var quux_error_data: QuuxErr = undefined;
quux(&quux_error_data) catch |err| {
    error_data = .{.quux = quux_error_data};
    return err;
};

When I would have liked to write:

   try foo();
   try bar();
   try quux();

Is there a nicer way to compose error values with this pattern?

Good question, yes there is:

andy@bark ~/s/zig (master)> g 'fn fail(' src
src/Sema.zig:pub fn fail(
src/codegen/c.zig:    fn fail(f: *Function, comptime format: []const u8, args: anytype) error{ AnalysisFail, OutOfMemory } {
src/codegen/c.zig:    fn fail(dg: *DeclGen, comptime format: []const u8, args: anytype) error{ AnalysisFail, OutOfMemory } {
src/codegen/spirv.zig:    pub fn fail(self: *NavGen, comptime format: []const u8, args: anytype) Error {
src/arch/x86_64/CodeGen.zig:fn fail(self: *Self, comptime format: []const u8, args: anytype) InnerError {
src/arch/x86_64/Lower.zig:pub fn fail(lower: *Lower, comptime format: []const u8, args: anytype) Error {
src/arch/x86_64/Emit.zig:fn fail(emit: *Emit, comptime format: []const u8, args: anytype) Error {
src/translate_c.zig:fn fail(
src/translate_c.zig:    fn fail(self: *MacroCtx, c: *Context, comptime fmt: []const u8, args: anytype) !void {
src/Package/Fetch.zig:fn fail(f: *Fetch, msg_tok: std.zig.Ast.TokenIndex, msg_str: u32) RunError {
src/Package/Manifest.zig:    fn fail(
src/link.zig:    pub fn fail(diags: *Diags, comptime format: []const u8, args: anytype) error{LinkFailure} {

I find your example a little unrealistic, because I don't see why you would have 3 different error types. By making them the same, then you can introduce a fail helper function which has return type error{AlreadyReported}. Then error.AlreadyReported is used to indicate the error state has already been recorded somewhere and you can keep using try.

I don't see why you would have 3 different error types

Because I'm calling three different apis that all use this error pattern and have different values associated with their errors. The values are actually useful too, so I don't want to just turn everything into a string error message.

In your examples you have AnalysisFail, InnerError, LinkFailure etc. If you have some zig code that you want to analyze, codegen and link, then what error value do you return? Is it always just an opaque string?

Considering how often we work with errors and how useful it is to have detailed information on the errors is, I don't think the fact that we can work around it is a valid reason to not make it a better experience

Maybe I missed it somewhere, but is there a technical reason why we seem opposed to enabling errors with payloads? Is it anti-the_thesis_of_zig in some way to provide that type of functionality?

The biggest reason why not is lifetime issues.
Consider:

const ParsingError = error
{
    BadToken: { line: u32, char: u32},
    UnknownIdentifier: { identifier: u8[] }
};

fn parse(text: u8[]) Result!ParsingError { ... }

In the case of BadToken, it is easy to handle, you just return a struct payload, simple.
What about UnknownIdentifier? If you have that, you may need to free the memory.

const text = getText();
defer allocator.free(text);
const result = try parse(text);
...

Now what happens?
You return a pointer to invalid memory, probably.
And you need to handle this somehow.

The problem here is that this just doesn't compose.