package errors

Import Path (on

Dependency Relation
	imports 9 packages, and imported by 24 packages

Involved Source Files adaptor.go Package errors implements functions to manipulate errors. This package expands "errors" with stack traces and explicit error wrapping. errors.go format.go frame.go into.go join_go120.go must.go trace.go wrap.go
Code Examples package main import ( "fmt" "time" ) // MyError is an error implementation that includes a time and message. type MyError struct { When time.Time What string } func (e MyError) Error() string { return fmt.Sprintf("%v: %v", e.When, e.What) } func oops() error { return MyError{ time.Date(1989, 3, 15, 22, 30, 0, 0, time.UTC), "the file system has gone away", } } func main() { if err := oops(); err != nil { fmt.Println(err) } } package main import ( "fmt" "os" "" ) func main() { _, err := os.Open("non-existing") if err != nil { var pathError *os.PathError if errors.As(err, &pathError) { fmt.Println("Failed at path:", pathError.Path) } } } package main import ( "fmt" "" ) type MyError2 struct { Message string frame errors.Frame } func (m *MyError2) Error() string { return m.Message } func (m *MyError2) Format(f fmt.State, c rune) { // implements fmt.Formatter errors.FormatError(m, f, c) } func (m *MyError2) FormatError(p errors.Printer) error { // implements errors.Formatter p.Print(m.Message) if p.Detail() { m.frame.Format(p) } return nil } func main() { err := &MyError2{Message: "oops", frame: errors.Caller(1)} fmt.Printf("%v\n", err) fmt.Println() fmt.Printf("%+v\n", err) } package main import ( "fmt" "os" "" ) func main() { _, err := os.Open("non-existing") if err != nil { if pathError, ok := errors.Into[*os.PathError](err); ok { fmt.Println("Failed at path:", pathError.Path) } } } package main import ( "fmt" "net/url" "" ) func main() { r := errors.Must(url.Parse(``)) fmt.Println(r.String()) }
Package-Level Type Names (total 9, in which 4 are exported)
/* sort exporteds by: | */
A Formatter formats error messages. ( Formatter) Error() builtin.string FormatError prints the receiver's first error and returns the next error in the error chain, if any. Formatter : error func FormatError(f Formatter, s fmt.State, verb rune)
A Frame contains part of a call stack. Format prints the stack as error detail. It should be called from an error's Format implementation after printing any other error detail. Location reports the file, line, and function of a frame. The returned function may be "" even if file and line are not. func Caller(skip int) Frame func Cause(err error) (f Frame, r bool)
A Printer formats error messages. The most common implementation of Printer is the one provided by package fmt during Printf (as of Go 1.13). Localization packages such as typically provide their own implementations. Detail reports whether error detail is requested. After the first call to Detail, all text written to the Printer is formatted as additional detail, or ignored when detail has not been requested. If Detail returns false, the caller can avoid printing the detail at all. Print appends args to the message output. Printf writes a formatted string. func Formatter.FormatError(p Printer) (next error) func Frame.Format(p Printer)
A Wrapper provides context around another error. Unwrap returns the next error in the error chain. If there is no next error, Unwrap returns nil. * * *crypto/tls.CertificateVerificationError crypto/x509.SystemRootsError *encoding/json.MarshalerError *io/fs.PathError *net.DNSConfigError *net.OpError *net/url.Error *os.LinkError *os.SyscallError *strconv.NumError
Package-Level Functions (total 18, in which 16 are exported)
As finds the first error in err's chain that matches target, and if so, sets target to that error value and returns true. Otherwise, it returns false. The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap. An error matches target if the error's concrete value is assignable to the value pointed to by target, or if the error has a method As(interface{}) bool such that As(target) returns true. In the latter case, the As method is responsible for setting target. An error type might provide an As method so it can be treated as if it were a different error type. As panics if target is not a non-nil pointer to either a type that implements error, or to any interface type.
Caller returns a Frame that describes a frame on the caller's stack. The argument skip is the number of frames to skip over. Caller(0) returns the frame for the caller of Caller.
Cause returns first recorded Frame.
DisableTrace disables capturing caller frames.
Errorf creates new error with format.
FormatError calls the FormatError method of f with an errors.Printer configured according to s and verb, and writes the result to s.
Type Parameters: T: error Into finds the first error in err's chain that matches target type T, and if so, returns it. Into is type-safe alternative to As.
Is reports whether any error in err's chain matches target. The chain consists of err itself followed by the sequence of errors obtained by repeatedly calling Unwrap. An error is considered to match a target if it is equal to that target or if it implements a method Is(error) bool such that Is(target) returns true. An error type might provide an Is method so it can be treated as equivalent to an existing error. For example, if MyError defines func (m MyError) Is(target error) bool { return target == fs.ErrExist } then Is(MyError{}, fs.ErrExist) returns true. See syscall.Errno.Is for an example in the standard library.
Join returns an error that wraps the given errors. Any nil error values are discarded. Join returns nil if every value in errs is nil. The error formats as the concatenation of the strings obtained by calling the Error method of each element of errs, with a newline between each string. A non-nil error returned by Join implements the Unwrap() []error method. Available only for go 1.20 or superior.
Type Parameters: T: any Must is a generic helper, like template.Must, that wraps a call to a function returning (T, error) and panics if the error is non-nil.
New returns an error that formats as the given text. The returned error contains a Frame set to the caller's location and implements Formatter to show this information when printed with details.
Opaque returns an error with the same error formatting as err but that does not match err and cannot be unwrapped.
Trace reports whether caller stack capture is enabled.
Unwrap returns the result of calling the Unwrap method on err, if err's type contains an Unwrap method returning error. Otherwise, Unwrap returns nil.
Wrap error with message and caller.
Wrapf wraps error with formatted message and caller.
Package-Level Variables (total 2, neither is exported)
Package-Level Constants (total 2, neither is exported)