#structured errors

In principle I agree. In practice, it often means this boilerplate is between every line of the big-picture intended-behavior code - a serious worsening to readability, not to mention the experience of writing and editing the code:

if err != nil {

    // usually wrap+annotate error

    return err

}

Libraries, languages, and ecosystems need to represent errors in ways that don't lose structure.

It would be nice to also preserve full type information as long as possible, for anything that can use it. Within a programming language, this is often doable: error structures can remain native types, with all the richness of the type system, until they need to be serialized. But once serialized, you have to make choices about what types, if any, get first-class representations.

So the minimal universal interface is anything that can represent strings of human-readable text, lists, and maps. In languages and libraries, this means that the minimum API for errors should be:

is this a list of separate pieces of information? if so, then give me each of them.

is this a map of separate pieces of information? if so then give me the key and value of each of them.

so then this is a single piece of information: give me the string of it.

Real world errors in almost any nontrivial program are often inherently lists or maps of information. Errors from multiple retries or parallel operations. Errors gathering relevant information as they bubble up the call stack.

It is not enough for error information to be put in opaque forms like strings, because when the error has made it all the way up to wherever it is being handled or analyzed, we often need to be able to pull out those individual pieces, and you shouldn't need to know all formats and encodings that got mixed into the error string by every single API down the call stack.

In Plan 9, one insight was to make all errors strings - system calls return error strings, not error numbers that map to strings; programs return with exit strings, not exit status integers.

In Go, one insight was to allow any type to be an error so long as it can be turned into an error string. This allows errors to not throw away type information or smudge fields together into one string until it's time to output them as an error, giving code a lot more opportunity to easily and simply programmatically handle errors.

(Notice that these are part of the same design heritage. At least one of the UNIX guys went on to work on Plan 9 and then went on to work on Go.)

I do think that a public error type, with or without public error fields, might be appropriate sometimes.

However, I think Dave Cheney's thoughts about relying on error interfaces or using constant errors instead of public error types should be seriously considered whenever making an error type in Go.

The key point of structured errors is that relevant pieces of contextual information should be attached to an error in an accessible way instead of being swallowed or smudged into something like a string.

But structuring our errors manifests differently if our errors are plain old data returns, versus if our errors are exceptions, versus if our error handling involves monads, versus [...].

Part 2

A less obvious application of structuring your errors is that wrapper errors should also be structured. So stop writing errors like this:

    err = fmt.Errorf(

        "host=%q %w",

        host,

        err,

    )

Instead, write errors like this:

type RemoteError struct {

    Host    string,

    wrapped error,

}

func (err RemoteError) Error() string {

    return fmt.Sprintf(

        "host=%q %s",

        err.Host,

        err.wrapped,

    )

}

func (err RemoteError) Unwrap() error {

    return err.wrapped

}

/* ... */

    err = RemoteError{host, err}

Basically, the same reasoning and exceptions apply as for structured errors in general.

Stop writing errors like this:

    err := fmt.Errorf(

        "bad happened: foo=%q bar=%d",

        foo,

        bar,

    )

Instead, write errors like this:

type BadHappened struct {

    Foo string

    Bar int

}

func (err BadHappened) Error() string {

    return fmt.Sprintf(

        "bad happened: foo=%q bar=%d",

        err.Foo,

        err.Bar,

    )

}

/* ... */

    err := BadHappened{Foo: foo, Bar: bar}

Unless your code doesn't matter, or the outputs of your code don't matter, or you know you will never need to change how your errors are logged and parsed, or you control the full stack of code from error generation through logging to analysis. Then you should do the first way, because it is faster.

But if you are writing errors that other code receives, especially if you are writing a library which is used by code you do not control, then expose all of the separate pieces of your error in a way that is meaningful and accessible in the language.