Skip to content

Errors on the wire

An error that crosses a process boundary usually arrives as a string. Its sentinel no longer matches, its hint is a fragment of text, and its kind is gone. errors/wire exists so the receiving process can treat the error as the sending one did.

One model, many formats

Every format translates between bytes and one model, and every decision about what a layer becomes on the wire is made once, in wire, before any format sees it. That is why two formats agree: they are not two implementations kept in step, but two renderings of the same tree. The conformance suite holds a new format to that.

JSON is in the core because it costs nothing new: this module already links encoding/json through log/slog. Protobuf is a separate module, because it brings a dependency nobody who does not use it should carry. Any other format is someone's codec, built against the same schema.

The edge chooses, not the error

It is tempting to have the code that makes an error say how it should travel. It cannot know. The same error may leave one process as an HTTP body to a browser and as a gRPC detail to another service. The place it leaves knows, and so does the receiver, through what it says it accepts. So the choice is made at the edge, once, and errors carry no format at all.

A wrapper that encoded itself was tried, and it fails twice. json.Marshal sees only the outermost value, so once anything wraps the error the encoding is lost without complaint. And a type that marshals itself takes over slog's JSON output as well.

Identity by registration

errors.Is compares pointers, and a pointer means nothing in another process. So a sentinel's kind is its identity on the wire: NewSentinel registers the instance under its kind, and a receiver that links the same package maps the kind back to the same pointer. The standard library's own sentinels are registered under reserved kinds, because ctx.Err() == context.Canceled is how callers check them.

Strangers are kept, not dropped

A receiver will meet layers it has never heard of: a newer kind, or a wrapper from a package it does not link. Each decodes to a layer that keeps its message, its kind and everything below it, so every reader keeps working past it. A process that relays the error forwards that layer exactly as it arrived.

Untrusted by default

The bytes come from another process, which may be hostile or simply newer. So decoding is bounded, a malformed document fails rather than half-decodes, and a panic in a consumer's own codec fails that decode instead of the process. Stacks are not sent unless asked for, because a stack is a map of your code.

The decisions behind each of these are in spec 0003, errors that cross a process boundary, on this project's wiki.