Golang Errors: Wrap, errors.Is, errors.As and Custom Types

Three kinds of errors

Go code uses three shapes of error, from simplest to richest:

1. An ad hoc error: errors.New("...") or fmt.Errorf("...") created on the spot. Callers can only read the message.
2. A sentinel error: a package-level variable such as io.EOF. Callers can test for it with errors.Is.
3. An error type: a struct with an Error() method, carrying fields. Callers can extract it with errors.As and read the fields.

Pick the simplest one that lets callers do what they need.

Sentinel errors

A sentinel is an error value declared once and compared by identity. Names start with Err by convention.

package main

import (
	"errors"
	"fmt"
)

var (
	ErrNotFound   = errors.New("not found")
	ErrOutOfStock = errors.New("out of stock")
)

var stock = map[string]int{"mug": 3, "cap": 0}

func buy(item string) error {
	n, ok := stock[item]
	if !ok {
		return fmt.Errorf("buy %q: %w", item, ErrNotFound)
	}
	if n == 0 {
		return fmt.Errorf("buy %q: %w", item, ErrOutOfStock)
	}
	stock[item]--
	return nil
}

func main() {
	for _, item := range []string{"mug", "cap", "hat"} {
		err := buy(item)
		switch {
		case err == nil:
			fmt.Println(item, "bought")
		case errors.Is(err, ErrOutOfStock):
			fmt.Println(item, "is out of stock, notify me later")
		case errors.Is(err, ErrNotFound):
			fmt.Println(err)
		}
	}
}

Output:

mug bought
cap is out of stock, notify me later
buy "hat": not found

Two errors.New calls with the same text produce different errors: errors.New("x") == errors.New("x") is false. That is why a sentinel must be a single shared variable.

Sentinels become part of your package's API. Once callers check for ErrNotFound, you cannot stop returning it without breaking them. Export only the ones callers genuinely need to branch on.

Custom error types

When the caller needs details (which field, which status code, which retry delay), define a type.

package main

import (
	"errors"
	"fmt"
)

type ValidationError struct {
	Field  string
	Reason string
}

func (e *ValidationError) Error() string {
	return fmt.Sprintf("%s: %s", e.Field, e.Reason)
}

func validateAge(age int) error {
	if age < 0 || age > 150 {
		return &ValidationError{Field: "age", Reason: "must be between 0 and 150"}
	}
	return nil
}

func register(age int) error {
	if err := validateAge(age); err != nil {
		return fmt.Errorf("register: %w", err)
	}
	return nil
}

func main() {
	err := register(200)
	fmt.Println(err)

	var ve *ValidationError
	if errors.As(err, &ve) {
		fmt.Println("bad field:", ve.Field)
	}
}

Output:

register: age: must be between 0 and 150
bad field: age

The method has a pointer receiver and the function returns &ValidationError{...}, so the target for errors.As is a *ValidationError, and you pass its address (&ve, a **ValidationError). Getting that level wrong is the classic errors.As mistake: with a value receiver you would return ValidationError{...} and declare var ve ValidationError. go vet catches the most common slip, passing ve instead of &ve: second argument to errors.As must be a non-nil pointer to either a type that implements error, or to any interface type.

Wrapping with %w

fmt.Errorf with %w returns an error that remembers the one it wraps. Each layer adds context and keeps the chain intact.

package main

import (
	"errors"
	"fmt"
)

var ErrTimeout = errors.New("timeout")

func dial() error    { return ErrTimeout }
func connect() error { return fmt.Errorf("connect db: %w", dial()) }
func start() error   { return fmt.Errorf("start: %w", connect()) }

func main() {
	err := start()
	fmt.Println(err)

	// Walk the chain by hand.
	for e := err; e != nil; e = errors.Unwrap(e) {
		fmt.Printf("  %T: %v\n", e, e)
	}

	fmt.Println(errors.Is(err, ErrTimeout))

	hidden := fmt.Errorf("start: %v", connect()) // %v: text only
	fmt.Println(errors.Is(hidden, ErrTimeout))
}

Output:

start: connect db: timeout
  *fmt.wrapError: start: connect db: timeout
  *fmt.wrapError: connect db: timeout
  *errors.errorString: timeout
true
false

With %v the message is the same but the chain is cut, so errors.Is returns false. Choose %w when callers should be able to see the cause, %v when the cause is an implementation detail you do not want them to depend on.

Since Go 1.20, one call may wrap several errors: fmt.Errorf("%w; %w", err1, err2). errors.Is then matches either one.

errors.Join: several errors at once

Validation and cleanup often produce more than one error. errors.Join (Go 1.20) bundles them.

package main

import (
	"errors"
	"fmt"
)

var ErrRequired = errors.New("required")

type Form struct {
	Name, Email string
	Age         int
}

func (f Form) Validate() error {
	var errs []error
	if f.Name == "" {
		errs = append(errs, fmt.Errorf("name: %w", ErrRequired))
	}
	if f.Email == "" {
		errs = append(errs, fmt.Errorf("email: %w", ErrRequired))
	}
	if f.Age < 0 {
		errs = append(errs, errors.New("age: negative"))
	}
	return errors.Join(errs...) // nil when errs is empty
}

func main() {
	err := Form{Age: -1}.Validate()
	fmt.Println(err)
	fmt.Println("---")
	fmt.Println(errors.Is(err, ErrRequired))
	fmt.Println(Form{Name: "Ana", Email: "a@x.com"}.Validate() == nil)
}

Output:

name: required
email: required
age: negative
---
true
true

errors.Join returns nil when every argument is nil, so the function above needs no special case for "no errors".

Unwrap and Is methods

errors.Is and errors.As find wrapped errors by calling an Unwrap method. A custom type that holds a cause should expose it:

package main

import (
	"errors"
	"fmt"
	"io/fs"
	"os"
)

type QueryError struct {
	Query string
	Err   error
}

func (e *QueryError) Error() string { return "query " + e.Query + ": " + e.Err.Error() }
func (e *QueryError) Unwrap() error { return e.Err }

func main() {
	_, openErr := os.Open("/no/such/db")
	err := &QueryError{Query: "SELECT 1", Err: openErr}

	fmt.Println(err)
	fmt.Println(errors.Is(err, fs.ErrNotExist)) // found through Unwrap
}

A type that wraps several errors implements Unwrap() []error instead.

A type can also define Is(target error) bool to decide equality itself, for example to match any *HTTPError with the same status code. You rarely need it; wrapping a sentinel and returning it from Unwrap usually does the job.

The typed nil trap

Never declare an error variable with your concrete type and return it through error:

func check() error {
	var err *ValidationError // nil pointer
	// ... no problem found
	return err // non-nil error! Its type is *ValidationError
}

The caller's if err != nil is true, because an interface holding a typed nil pointer is not nil. Return a literal nil on success, and keep local error variables typed as error. The interfaces page explains why.

Which kind to choose

Common mistakes

• Comparing wrapped errors with ==. Use errors.Is.
• Passing a non-pointer to errors.As. It needs a pointer to a variable of the target type.
• Creating a "sentinel" inside a function. return errors.New("not found") makes a new value each call; callers cannot compare against it.
• Exporting every error. Each exported sentinel or type is an API promise.
• Matching on err.Error(). Strings are for humans.