As

func As(err error, target any) bool

Added in Go 1.13

As searches err and its wrapped errors for the first value that matches target. On success it assigns that value to target and returns true; otherwise it returns false.

A value matches when it is assignable to the type pointed to by target, or when it implements a successful As(any) bool method. A custom As method is responsible for assigning the target value.

target must be a non-nil pointer to an error type or any interface type. An invalid target causes a panic. For most uses on Go 1.26 or later, the standard library recommends AsType.

Example

_, err := os.Open("missing.txt")
var pathError *fs.PathError

if errors.As(err, &pathError) {
    fmt.Println(pathError.Path)
}

Output

missing.txt

AsType

func AsType[E error](err error) (E, bool)

Added in Go 1.26

AsType searches the error tree for the first value matching type E. It returns that value with true. If nothing matches, it returns the zero value of E with false.

A value matches when a type assertion to E succeeds, or when the error supplies a successful As(any) bool method for a non-nil *E target.

Example

_, err := os.Open("missing.txt")

if pathError, ok := errors.AsType[*fs.PathError](err); ok {
    fmt.Println(pathError.Op)
}

Output

open

Is

func Is(err, target error) bool

Added in Go 1.13

Is reports whether any error in the tree matches target. The target must be comparable. It is normally safer than direct equality because it continues through wrapped errors.

An error matches when it equals target, or when it implements an Is(error) bool method that reports a match. A custom Is method should compare only the current values and should not unwrap either error itself.

Example

_, err := os.Open("missing.txt")
fmt.Println(errors.Is(err, fs.ErrNotExist))

Output

true

Join

func Join(errs ...error) error

Added in Go 1.20

Join combines the non-nil arguments into one error. It returns nil when every argument is nil. The combined message contains each error message on its own line.

A non-nil result implements Unwrap() []error, so its members can be found with Is, As, or AsType.

Example

readErr := errors.New("read failed")
writeErr := errors.New("write failed")
err := errors.Join(readErr, nil, writeErr)

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

Output

read failed
write failed
true

New

func New(text string) error

New returns an error whose message is text. Each call creates a distinct error value, even when two calls receive identical text. Declare and reuse a package-level value when callers need a sentinel error.

Example

first := errors.New("not ready")
second := errors.New("not ready")

fmt.Println(first)
fmt.Println(first == second)

Output

not ready
false

Unwrap

func Unwrap(err error) error

Added in Go 1.13

Unwrap returns the value produced by an Unwrap() error method. If that method is absent, it returns nil.

It does not call Unwrap() []error, so it does not unwrap values returned by Join. Use Is, As, or AsType to search a complete error tree.

Example

inner := errors.New("disk full")
outer := fmt.Errorf("save file: %w", inner)

fmt.Println(errors.Unwrap(outer))

Output

disk full

ErrUnsupported

var ErrUnsupported = New("unsupported operation")

ErrUnsupported means that an operation cannot be performed by the current system or implementation. Code should usually wrap it with useful context instead of returning it directly.

Callers can test the returned error with errors.Is(err, errors.ErrUnsupported). Functions returning an error that wraps this value should document when it may occur.

Example

func compress() error {
    return fmt.Errorf("gzip: %w", errors.ErrUnsupported)
}

err := compress()
fmt.Println(errors.Is(err, errors.ErrUnsupported))

Output

true