1 // Package errors provides simple error handling primitives.
3 // The traditional error handling idiom in Go is roughly akin to
9 // which when 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 // together with 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
26 // errors.WithMessage functions destructure errors.Wrap into its component
27 // operations: annotating an error with a stack trace and with a message,
30 // Retrieving the cause of an error
32 // Using errors.Wrap constructs a stack of errors, adding context to the
33 // preceding error. Depending on the nature of the error it may be necessary
34 // to reverse the operation of errors.Wrap to retrieve the original error
35 // for inspection. Any error value which implements this interface
37 // type causer interface {
41 // can be inspected by errors.Cause. errors.Cause will recursively retrieve
42 // the topmost error that does not implement causer, which is assumed to be
43 // the original cause. For example:
45 // switch err := errors.Cause(err).(type) {
47 // // handle specifically
52 // Although the causer interface is not exported by this package, it is
53 // considered a part of its stable public interface.
55 // Formatted printing of errors
57 // All error values returned from this package implement fmt.Formatter and can
58 // be formatted by the fmt package. The following verbs are supported:
60 // %s print the error. If the error has a Cause it will be
61 // printed recursively.
63 // %+v extended format. Each Frame of the error's StackTrace will
64 // be printed in detail.
66 // Retrieving the stack trace of an error or wrapper
68 // New, Errorf, Wrap, and Wrapf record a stack trace at the point they are
69 // invoked. This information can be retrieved with the following interface:
71 // type stackTracer interface {
72 // StackTrace() errors.StackTrace
75 // The returned errors.StackTrace type is defined as
77 // type StackTrace []Frame
79 // The Frame type represents a call site in the stack trace. Frame supports
80 // the fmt.Formatter interface that can be used for printing information about
81 // the stack trace of this error. For example:
83 // if err, ok := err.(stackTracer); ok {
84 // for _, f := range err.StackTrace() {
85 // fmt.Printf("%+s:%d", f)
89 // Although the stackTracer interface is not exported by this package, it is
90 // considered a part of its stable public interface.
92 // See the documentation for Frame.Format for more details.
100 // New returns an error with the supplied message.
101 // New also records the stack trace at the point it was called.
102 func New(message string) error {
109 // Errorf formats according to a format specifier and returns the string
110 // as a value that satisfies error.
111 // Errorf also records the stack trace at the point it was called.
112 func Errorf(format string, args ...interface{}) error {
114 msg: fmt.Sprintf(format, args...),
119 // fundamental is an error that has a message and a stack, but no caller.
120 type fundamental struct {
125 func (f *fundamental) Error() string { return f.msg }
127 func (f *fundamental) Format(s fmt.State, verb rune) {
131 io.WriteString(s, f.msg)
132 f.stack.Format(s, verb)
137 io.WriteString(s, f.msg)
139 fmt.Fprintf(s, "%q", f.msg)
143 // WithStack annotates err with a stack trace at the point WithStack was called.
144 // If err is nil, WithStack returns nil.
145 func WithStack(err error) error {
155 type withStack struct {
160 func (w *withStack) Cause() error { return w.error }
162 func (w *withStack) Format(s fmt.State, verb rune) {
166 fmt.Fprintf(s, "%+v", w.Cause())
167 w.stack.Format(s, verb)
172 io.WriteString(s, w.Error())
174 fmt.Fprintf(s, "%q", w.Error())
178 // Wrap returns an error annotating err with a stack trace
179 // at the point Wrap is called, and the supplied message.
180 // If err is nil, Wrap returns nil.
181 func Wrap(err error, message string) error {
195 // Wrapf returns an error annotating err with a stack trace
196 // at the point Wrapf is called, and the format specifier.
197 // If err is nil, Wrapf returns nil.
198 func Wrapf(err error, format string, args ...interface{}) error {
204 msg: fmt.Sprintf(format, args...),
212 // WithMessage annotates err with a new message.
213 // If err is nil, WithMessage returns nil.
214 func WithMessage(err error, message string) error {
224 // WithMessagef annotates err with the format specifier.
225 // If err is nil, WithMessagef returns nil.
226 func WithMessagef(err error, format string, args ...interface{}) error {
232 msg: fmt.Sprintf(format, args...),
236 type withMessage struct {
241 func (w *withMessage) Error() string { return w.msg + ": " + w.cause.Error() }
242 func (w *withMessage) Cause() error { return w.cause }
244 func (w *withMessage) Format(s fmt.State, verb rune) {
248 fmt.Fprintf(s, "%+v\n", w.Cause())
249 io.WriteString(s, w.msg)
254 io.WriteString(s, w.Error())
258 // Cause returns the underlying cause of the error, if possible.
259 // An error value has a cause if it implements the following
262 // type causer interface {
266 // If the error does not implement Cause, the original error will
267 // be returned. If the error is nil, nil will be returned without further
269 func Cause(err error) error {
270 type causer interface {
275 cause, ok := err.(causer)