Go Reference ยท Errors, I/O and Files
Go errors package
Reference for the Go errors package: New, Is, As, Join, Unwrap and ErrUnsupported, plus how error wrapping and error chains work with fmt.Errorf and %w.
In Go an error is any value that has an Error() string method. The package errors provides the small set of tools around that idea: New creates a simple error, Is and As look through a chain of wrapped errors, Join combines several errors, and Unwrap peels off one layer.
Wrapping is the key concept. A function that fails can add context and keep the original error inside the new one, usually with fmt.Errorf("...: %w", err). The result is a chain, and errors.Is and errors.As walk that chain so callers can still recognize the root cause.
err := fmt.Errorf("load config: %w", os.ErrNotExist) fmt.Println(errors.Is(err, os.ErrNotExist)) // true
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Syntax
func New(text string) error func Is(err, target error) bool func As(err error, target any) bool func Join(errs ...error) error func Unwrap(err error) error var ErrUnsupported error
| Function | Description |
|---|---|
New(text) |
Returns a new error whose Error() is text. Every call returns a distinct value. |
Is(err, target) |
Reports whether any error in the chain of err matches target. |
As(err, target) |
Finds the first error in the chain assignable to the type target points to, and stores it there. |
Join(errs...) |
Combines non-nil errors into one; returns nil if all are nil. |
Unwrap(err) |
Returns the result of err's Unwrap() error method, or nil. |
Errors / panics: As panics if target is not a non-nil pointer to a type implementing error or to an interface. go vet catches this mistake.
Usage notes
- The error interface is just
Error() string. Custom error types add fields, and optional methods such asUnwrap() error,Unwrap() []error,Is(error) boolandAs(any) boolcustomize how the chain is searched. - Do not compare with
==after wrapping.err == ErrEmptyfails once someone wraps the error; useerrors.Is. - Sentinel errors are package-level variables created with
errors.New, namedErrSomething. They become part of your API, so export them only when callers need to test for them. ErrUnsupported(Go 1.21) is a standard way to say that an operation is not supported; wrap it soerrors.Is(err, errors.ErrUnsupported)is true.- Messages: start them in lowercase and omit the trailing punctuation, because errors are usually embedded in longer messages.
- A nil error means success. Never return a typed nil pointer as an
error; see Nil interface pitfall. errors.Joinneeds Go 1.20, as does wrapping several errors with multiple%wverbs.