1 // Package errors provides simple error handling primitives.
3 // The traditional error handling idiom in Go is roughly akin to
9 // which applied recursively up the call stack results in error reports
10 // without context or debugging information. The errors package allows
11 // programmers to add context to the failure path in their code in a way
12 // that does not destroy the original value of the error.
14 // Adding context to an error
16 // The errors.Wrap function returns a new error that adds context to the
17 // original error by recording a stack trace at the point Wrap is called,
18 // and the supplied message. For example
20 // _, err := ioutil.ReadAll(r)
22 // return errors.Wrap(err, "read failed")
25 // If additional control is required the errors.WithStack and errors.WithMessage
26 // functions destructure errors.Wrap into its component operations of annotating
27 // an error with a stack trace and an a message, respectively.
29 // Retrieving the cause of an error
31 // Using errors.Wrap constructs a stack of errors, adding context to the
32 // preceding error. Depending on the nature of the error it may be necessary
33 // to reverse the operation of errors.Wrap to retrieve the original error
34 // for inspection. Any error value which implements this interface
36 // type causer interface {
40 // can be inspected by errors.Cause. errors.Cause will recursively retrieve
41 // the topmost error which does not implement causer, which is assumed to be
42 // the original cause. For example:
44 // switch err := errors.Cause(err).(type) {
46 // // handle specifically
51 // causer interface is not exported by this package, but is considered a part
52 // of stable public API.
54 // Formatted printing of errors
56 // All error values returned from this package implement fmt.Formatter and can
57 // be formatted by the fmt package. The following verbs are supported
59 // %s print the error. If the error has a Cause it will be
60 // printed recursively
62 // %+v extended format. Each Frame of the error's StackTrace will
63 // be printed in detail.
65 // Retrieving the stack trace of an error or wrapper
67 // New, Errorf, Wrap, and Wrapf record a stack trace at the point they are
68 // invoked. This information can be retrieved with the following interface.
70 // type stackTracer interface {
71 // StackTrace() errors.StackTrace
74 // Where errors.StackTrace is defined as
76 // type StackTrace []Frame
78 // The Frame type represents a call site in the stack trace. Frame supports
79 // the fmt.Formatter interface that can be used for printing information about
80 // the stack trace of this error. For example:
82 // if err, ok := err.(stackTracer); ok {
83 // for _, f := range err.StackTrace() {
84 // fmt.Printf("%+s:%d", f)
88 // stackTracer interface is not exported by this package, but is considered a part
89 // of stable public API.
91 // See the documentation for Frame.Format for more details.
99 // New returns an error with the supplied message.
100 // New also records the stack trace at the point it was called.
101 func New(message string) error {
108 // Errorf formats according to a format specifier and returns the string
109 // as a value that satisfies error.
110 // Errorf also records the stack trace at the point it was called.
111 func Errorf(format string, args ...interface{}) error {
113 msg: fmt.Sprintf(format, args...),
118 // fundamental is an error that has a message and a stack, but no caller.
119 type fundamental struct {
124 func (f *fundamental) Error() string { return f.msg }
126 func (f *fundamental) Format(s fmt.State, verb rune) {
130 io.WriteString(s, f.msg)
131 f.stack.Format(s, verb)
136 io.WriteString(s, f.msg)
138 fmt.Fprintf(s, "%q", f.msg)
142 // WithStack annotates err with a stack trace at the point WithStack was called.
143 // If err is nil, WithStack returns nil.
144 func WithStack(err error) error {
154 type withStack struct {
159 func (w *withStack) Cause() error { return w.error }
161 func (w *withStack) Format(s fmt.State, verb rune) {
165 fmt.Fprintf(s, "%+v", w.Cause())
166 w.stack.Format(s, verb)
171 io.WriteString(s, w.Error())
173 fmt.Fprintf(s, "%q", w.Error())
177 // Wrap returns an error annotating err with a stack trace
178 // at the point Wrap is called, and the supplied message.
179 // If err is nil, Wrap returns nil.
180 func Wrap(err error, message string) error {
194 // Wrapf returns an error annotating err with a stack trace
195 // at the point Wrapf is call, and the format specifier.
196 // If err is nil, Wrapf returns nil.
197 func Wrapf(err error, format string, args ...interface{}) error {
203 msg: fmt.Sprintf(format, args...),
211 // WithMessage annotates err with a new message.
212 // If err is nil, WithMessage returns nil.
213 func WithMessage(err error, message string) error {
223 type withMessage struct {
228 func (w *withMessage) Error() string { return w.msg + ": " + w.cause.Error() }
229 func (w *withMessage) Cause() error { return w.cause }
231 func (w *withMessage) Format(s fmt.State, verb rune) {
235 fmt.Fprintf(s, "%+v\n", w.Cause())
236 io.WriteString(s, w.msg)
241 io.WriteString(s, w.Error())
245 // Cause returns the underlying cause of the error, if possible.
246 // An error value has a cause if it implements the following
249 // type causer interface {
253 // If the error does not implement Cause, the original error will
254 // be returned. If the error is nil, nil will be returned without further
256 func Cause(err error) error {
257 type causer interface {
262 cause, ok := err.(causer)