Go Error Wrapping

External

• https://pkg.go.dev/errors

Internal

• Go Error Handling

Overview

The error mechanism in Go allows "wrapping" error instances into other error instances, while preserving the wrapped error identity. This pattern supports building an error tree that is useful in preserving context.

Error wrapping should be the preferred pattern to use when we want to provide additional context to an error

Error wrapping and returning the result to the upper layer is just one of the error handling patterns in Go. The others are fully handling the error without returning it, simply returning it without any modification, and returning a new annotated error.

This pattern consists in wrapping an error returned by the underlying layer into an "outer" error instance. This is typically done to add information relevant to the context that caught the error being processed. For example, if access to a database fails with access denied, handing the error may consist in wrapping the original error into a new error that also includes the user and the operation, which is richer context that can help with troubleshooting the problem by the operators of the program.

Another situation when wrapping the error is useful is when we want to mark the error as a specific type by wrapping into a custom error type. For example, the same access denied to the database can be wrapped into a "Forbidden" error type, so a hypothetical HTTP handling layer that receives the error returns a 403 status code.

These approaches can be combined: we can at the same time add more context and mark an error.

In all these cases, the source error remains available for further inspection. This is different from and more than annotating the error, because it involves embedding an actual error instance, preserving its unique identity, instead of concatenating strings. The wrapped error can be accessed with the errors.Unwrap() function, and the error tree can be navigated recursively this way.

One disadvantage of error wrapping is that introduces potential coupling. If a calling layer checks for a specific wrapped error, and the called layer changes its implementation and returns a different wrapped error, this will break the calling layer. If this a problem, annotating the errors instead of wrapping them is a better approach.

Wrap the Error

Individual errors are typically wrapped with fmt.Errorf(). To wrap multiple error instances into a single outer error, use errors.Join().

Wrap an Individual Error

A typical error handling pattern is to handle an error returned by a function invocation by "wrapping" it into an outer error instance that provides additional context, in form of an addition error text message.The approach is different from annotating the error because it creates a new error instance while preserving the identity of the wrapped error. The wrapped error is still reachable by introspecting the error tree with methods like errors.Is() or errors.As().

The error is wrapped with fmt.Errorf() and %w conversion character:

if err != nil {
  outer := fmt.Errorf("%w: additional context", err)
  return outer
}

fmt.Errorf() call creates a new error instance whose Error() method concatenates the error message provided as argument and the inner error message:

original context: additional context

The outer error assumes the logical identity of the inner error: the outer error "is" all its inner errors. This can be checked programmatically with errors.Is() function:

errors.Is(outer, err) // returns true

The outer error becomes the direct ancestor of the wrapped error, and successive invocations of the fmt.Errorf() result in an error tree, where the identity of the wrapped errors can be checked with errors.Is(). More details on errors.Is() can be found below. The wrapped error can be obtained from the outer error by calling errors.Unwrap().

Invoking fmt.Errorf() with More that One Error Argument

fmt.Errorf() is conventionally invoked with just one "%w" conversion character and one error argument. This results in building a degenerated tree that is in fact a linked list. However, more than one error can be provided as argument to fmt.Errorf():

err := fmt.Errorf("err")
err2 := fmt.Errorf("err2")
outer := fmt.Errorf("outer: %w %w", err, err2)
println(errors.Is(outer, err))  // prints true
println(errors.Is(outer, err2)) // prints true

The behavior of errors.Unwrap() seems to be a bit inconsistent in this situation: it won't return the error instances, but nil. This seems to imply that fmt.Errors() should only be used to wrap a single error.

errors.Join()

https://pkg.go.dev/errors#Join

Join returns an error that wraps the given errors. Any nil error values are discarded. Join returns nil if every value provided as argument is nil. The error formats as the concatenation of the strings obtained by calling the Error() method of each element, with a newline between each string.

Inspect the Error Tree

errors.Is()

https://pkg.go.dev/errors#Is

The presence of a specific error instance wrapped inside an outer error, as a direct or indirect descendant in the error tree rooted in the outer error, can be confirmed with errors.Is(<outer_error>, <sought_for_error>) function. The function introspects the outer_error's error tree by repeatedly calling Unwrap().

Always prefer errors.Is() over the == equality operator. errors.Is() is designed to work with both individual errors and wrapped errors. Furthermore, errors.Is() is safe to use if the first argument, outer_error is nil.

orig := fmt.Errorf("original error")
intermediate := fmt.Errorf("intermediate error: %w", orig)
outer := fmt.Errorf("final intermediate error: %w", intermediate)
println(errors.Is(outer, intermediate)) // prints "true"
println(errors.Is(outer, orig))         // prints "true"
println(errors.Is(intermediate, orig))  // prints "true"

errors.As()

https://pkg.go.dev/errors#As

errors.As(<outer_error>, <an_error_similar_to_the_error_sought_after>) provides a safe way to locate the first error in the error tree that matches the error type of the error instance provided as the second argument. If no match is found, the function returns false. The function introspects the outer_error's error tree by repeatedly calling Unwrap(). errors.As() is similar, but weaker form of errors.Is() with the difference that types, and not identities are compared. Always prefer errors.As() over type assertions.

errors.Unwrap()

https://pkg.go.dev/errors#Unwrap

errors.Unwrap(<outer_error>) returns the inner error instance wrapped inside the outer error by a fmt.Errorf("%w") call. errors.Unwrap() does not unwrap errors returned by errors.Join().

orig := fmt.Errorf("original error")
intermediate := fmt.Errorf("intermediate error: %w", orig)
outer := fmt.Errorf("final intermediate error: %w", intermediate)
println(errors.Unwrap(outer) == intermediate) // prints true
println(errors.Unwrap(intermediate) == orig)  // prints true

When more than one errors is wrapped with fmt.Errorf(), errors.Unwrap() returns nil. This seems to be a bit inconsistent, and implies that fmt.Errorf() should only be used to wrap single errors.

Unwrap() errror Implementation

Example:

Custom Error Types | Unwrap() implementation