Go Error Wrapping

External

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

Internal

• Go Error Handling

Overview

Go error mechanism 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 and returning the result to the upper layer is one of the common 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.

The 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. However, wrapping the error is more than error annotation, because it involves embedding an actual error instance, preserving its unique identity, instead of concatenating strings.

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("additional context: %w", 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:

additional context: original 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().

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 wrapped error 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:

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.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.28.29|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