Go Error Wrapping

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().

An error instance can be wrapped with fmt.Errorf() and %w conversion character.

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

The wrapped error message, assuming that the original error is "initial information", with be:

additional information: initial information

Document errors.Unwrap()

errors.Join()

Inspect the Error Tree

TO DEPLETE

Checking for Wrapped Errors

A wrapped error can be identified in an enclosing error with the errors.Is(<outer_error>, <sought_for_error>) function.

Need to understand errors.Is(), error tree, wrapping and unwrapping.

var BlueError = errors.New("some information")
var GreenError = errors.New("some information")

...

// wrap the error in an outer error
outerError := fmt.Errorf("addtional info: %w", BlueError)

if errors.Is(outerError, BlueError) {
  fmt.Println("found blue error")
}

if errors.Is(outerError, GreenError) {
  fmt.Println("found green error")
}

BlueError is correctly identified, even though both BlueError and GreenError carry the same string. How?