Go error handling: wrapping with %w, errors.Is and errors.As

What it is

In Go an error is any value whose type has an Error() string method; functions return it as the last result and nil means success. There are no exceptions: the Go FAQ explains the design as multi-value returns for ordinary failures plus panic/recover for truly exceptional conditions. Since Go 1.13 errors form a chain. fmt.Errorf("open config: %w", err) returns an error that implements Unwrap() error, and the errors package documentation describes how errors.Is and errors.As walk that tree (an error first, then its children, depth-first): Is compares against a target value, As finds the first error assignable to a target type and copies it out. errors.Join (Go 1.20) and fmt.Errorf with several %w verbs produce errors whose Unwrap returns []error. Go 1.26 adds the generic errors.AsType[E](err), which returns the typed value and a boolean.

Why it matters

Coming from Python or JavaScript, the reflex is try/except around a block; in Go every call site decides. Two habits from dynamic languages break here: comparing err.Error() strings, which change whenever a layer adds context, and comparing err == ErrNotFound with ==, which fails as soon as the error has been wrapped. The documentation states that errors.Is(err, fs.ErrExist) is preferable to err == fs.ErrExist for exactly that reason.

How to apply

• Declare sentinel errors as package variables (var ErrNotFound = errors.New("not found")) and structured errors as types with fields; callers match with errors.Is or errors.As.
• Wrap with %w when the caller may reasonably inspect the cause and %v when the cause is an implementation detail; the Go blog's guidance is to wrap an error to expose it to callers and not to wrap when doing so would expose implementation details.
• Add context once per layer in the form "what was being done: %w", lower-case and without trailing punctuation, so messages read as a chain from outermost to innermost.
• Handle or return, not both: logging an error and also returning it produces duplicate log lines at every level.
• Give a custom type an Is(error) bool method when it should compare equal to an existing sentinel; the package documentation describes this hook.

Pitfalls

%v silently breaks the chain. Wrapping a nil error creates a non-nil error. A function that returns a typed nil pointer as error returns a non-nil interface (see the interfaces article). Returning sql.ErrNoRows through %w from a repository ties callers to the database package, which is the blog's own example. panic is not a general error mechanism; reserve it for programmer errors and recover only at goroutine boundaries.