errors

errors.New, errors.Is, errors.As, errors.Join, and errors.Unwrap: sentinels, wrapping trees, and why Join is not unwrapped by Unwrap.

模块页正文目前为英文。

The errors package constructs and inspects error values. errors.New returns a distinct sentinel: two calls with the same text are not equal. errors.Is and errors.As walk an error tree created by wrapping. Official documentation describes wrapping as an Unwrap() error or Unwrap() []error method. This page does not repeat the fmt.Errorf %w example on the fmt page; it shows how Is, As, Join, and the Unwrap function treat that tree.

errors.Join was added in Go 1.20. It wraps several errors at once, discards nil values, and returns nil when every argument is nil. Examples were checked with Go 1.24.0.

Examples were checked against Go 1.24.0. See the official package documentation for the complete API.

Go reference overview →

API index

APISummary
errors.New, errors.Is, errors.Join, errors.UnwrapBuild sentinels, join several errors, and test membership in the tree. Unwrap does not unwrap a Join error.
errors.AsExtract a concrete error type from a wrapping tree. A nil or non-pointer target panics.

New, Is, Join, and Unwrap

errors.Is reports whether any error in the tree matches the target, by equality or by an Is method. A new errors.New("one") is a different value from an earlier errors.New("one"), so Is is false unless you keep the same sentinel. errors.Join(one, two) is an error whose Error text is the two messages separated by a newline. Official documentation says a non-nil Join result implements Unwrap() []error, so Is can see both one and two. The errors.Unwrap function only calls Unwrap() error, and official documentation states that it does not unwrap errors returned by Join.

errors.New, errors.Is, errors.Join, errors.Unwrap

func New(text string) error
func Is(err, target error) bool
func Join(errs ...error) error
func Unwrap(err error) error

Build sentinels, join several errors, and test membership in the tree. Unwrap does not unwrap a Join error.

ParameterDescription
textThe message stored by New. Each call returns a distinct value, even when the text is the same.
err, targetIs walks the tree of err looking for a match with target. A nil err is not a match.
errsJoin discards nil arguments and returns nil if every argument is nil.

Returns: New and Join return an error, or nil for Join when nothing remains. Is returns whether a match was found. Unwrap returns the next error, or nil when there is no Unwrap() error method.

  • Wrapping a single error with fmt.Errorf and %w is documented on the fmt page. Is walks that chain as well as a Join tree.
  • The joined Error() text was measured on Go 1.24.0 as the two messages with a newline between them.
go
package main

import (
	"errors"
	"fmt"
)

func main() {
	one := errors.New("one")
	two := errors.New("two")
	joined := errors.Join(one, two)
	fmt.Println(joined)
	fmt.Println(errors.Is(joined, one), errors.Is(joined, two))
	fmt.Println(errors.Is(joined, errors.New("one")))
	fmt.Println(errors.Unwrap(joined) == nil)
	fmt.Println(errors.Join(nil, nil) == nil)
}

Expected output

one
two
true true
false
true
true

Related: fmt.Errorf, os.ErrNotExist and errors.Is

Official documentation →

As and invalid targets

errors.As finds the first error in the tree that can be assigned to the value pointed to by target, sets that pointer, and returns true. Official documentation prefers As over a single type assertion when the concrete error may be wrapped. As panics if target is nil, or if it is not a non-nil pointer to an error type or to an interface. The panic text below was measured on Go 1.24.0.

errors.As

func As(err error, target any) bool

Extract a concrete error type from a wrapping tree. A nil or non-pointer target panics.

ParameterDescription
errThe error tree to search. Wrapping in this example uses fmt.Errorf with %w.
targetA non-nil pointer to an error type or to an interface. As writes the matched error through that pointer.

Returns: true if a match was found and target was set; otherwise false.

Errors

  • panic — Official documentation: As panics if target is not a non-nil pointer to a type that implements error, or to any interface type. The measured messages on Go 1.24.0 include "errors: target cannot be nil".
  • After a successful As, the pointer holds the matching value, here the *pathError that was wrapped.
go
package main

import (
	"errors"
	"fmt"
)

type pathError struct {
	Path string
}

func (e *pathError) Error() string {
	return "path " + e.Path
}

func main() {
	err := fmt.Errorf("open: %w", &pathError{Path: "a.txt"})
	var pe *pathError
	fmt.Println(errors.As(err, &pe), pe.Path)
	func() {
		defer func() { fmt.Println(recover()) }()
		_ = errors.As(err, nil)
	}()
}

Expected output

true a.txt
errors: target cannot be nil

Related: fmt.Errorf

Official documentation →