errors

package module
v0.16.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 1, 2022 License: BSD-2-Clause Imports: 7 Imported by: 2

README

errors

Package errors provides handful error handling primitives.

This package is forked from pingcap/errors which is another derivative of the popular pkg/errors package.

This errors package is different from pkg/errors or pingcap/errors in following ways:

  1. A new method AddStack is added to avoid the overhead of adding duplicate stacks to the error chain by calling WithStack. Generally, AddStack should be used instead of WithStack.

  2. Some helper functions to help migration from juju/errors with signature compatibility. This package use different implementation with pingcap/errors.

  3. A new error type withFields is added to pass context information of the error like logrus. Extra key-value context information can be attached to the error by calling functions WithFields, New, AddStack, WithStack, WithMessage or Wrap. The attached key-value information can be printed by using fmt.Sprint("%+v", err). Also the additional package logrus_ext can be used to automatically hook the context information when using with logrus.

  4. Group errors and multi errors handling primitives are added.

  5. Unlike pingcap/errors, the StackTrace and Frame types in this package are just aliases of the corresponding types from pkg/errors, which makes this package compatible with existing logrus hooks such as gelf hook and sentry hook.

  6. NOTE: this package does not follow the versioning of either pkg/errors or pingcap/errors.

For users who don't need the additional features from this package, the original pkg/errors package is highly recommended.

For latest information about packages pkg/errors and pingcap/errors, please refer to their websites.

Travis-CI AppVeyor GoDoc Report card Sourcegraph

Package errors provides simple error handling primitives.

go get github.com/pkg/errors

The traditional error handling idiom in Go is roughly akin to

if err != nil {
        return err
}

which applied recursively up the call stack results in error reports without context or debugging information. The errors package allows programmers to add context to the failure path in their code in a way that does not destroy the original value of the error.

Adding context to an error

The errors.Wrap function returns a new error that adds context to the original error. For example

_, err := ioutil.ReadAll(r)
if err != nil {
        return errors.Wrap(err, "read failed")
}

Retrieving the cause of an error

Using errors.Wrap constructs a stack of errors, adding context to the preceding error. Depending on the nature of the error it may be necessary to reverse the operation of errors.Wrap to retrieve the original error for inspection. Any error value which implements this interface can be inspected by errors.Cause.

type causer interface {
        Cause() error
}

errors.Cause will recursively retrieve the topmost error which does not implement causer, which is assumed to be the original cause. For example:

switch err := errors.Cause(err).(type) {
case *MyError:
        // handle specifically
default:
        // unknown error
}

Read the package documentation for more information.

Roadmap

With the upcoming Go2 error proposals this package is moving into maintenance mode. The roadmap for a 1.0 release is as follows:

  • 0.9. Remove pre Go 1.9 support, address outstanding pull requests (if possible)
  • 1.0. Final release.

Contributing

Because of the Go2 errors changes, this package is not accepting proposals for new functionality. With that said, we welcome pull requests, bug fixes and issue reports.

Before sending a PR, please discuss your change by raising an issue.

License

BSD-2-Clause

Documentation

Overview

Package errors provides simple error handling primitives.

The traditional error handling idiom in Go is roughly akin to 

if err != nil {
        return err
}

which when applied recursively up the call stack results in error reports without context or debugging information. The errors package allows programmers to add context to the failure path in their code in a way that does not destroy the original value of the error.

Adding context to an error

The errors.Wrap function returns a new error that adds context to the original error by recording a stack trace at the point Wrap is called, together with the supplied message. For example 

_, err := ioutil.ReadAll(r)
if err != nil {
        return errors.Wrap(err, "read failed")
}

If additional control is required, the errors.WithStack and errors.WithMessage functions destructure errors.Wrap into its component operations: annotating an error with a stack trace and with a message, respectively.

Retrieving the cause of an error

Using errors.Wrap constructs a stack of errors, adding context to the preceding error. Depending on the nature of the error it may be necessary to reverse the operation of errors.Wrap to retrieve the original error for inspection. Any error value which implements this interface 

type causer interface {
        Cause() error
}

can be inspected by errors.Cause. errors.Cause will recursively retrieve the topmost error that does not implement causer, which is assumed to be the original cause. For example: 

switch err := errors.Cause(err).(type) {
case *MyError:
        // handle specifically
default:
        // unknown error
}

Although the causer interface is not exported by this package, it is considered a part of its stable public interface.

Formatted printing of errors

All error values returned from this package implement fmt.Formatter and can be formatted by the fmt package. The following verbs are supported: 

%s    print the error. If the error has a Cause it will be
      printed recursively.
%v    see %s
%+v   extended format. Each Frame of the error's StackTrace will
      be printed in detail.

Retrieving the stack trace of an error or wrapper

New, Errorf, Wrap, and Wrapf record a stack trace at the point they are invoked. This information can be retrieved with the following interface: 

type stackTracer interface {
        StackTrace() errors.StackTrace
}

The returned errors.StackTrace type is defined as 

type StackTrace []Frame

The Frame type represents a call site in the stack trace. Frame supports the fmt.Formatter interface that can be used for printing information about the stack trace of this error. For example: 

if err, ok := err.(stackTracer); ok {
        for _, f := range err.StackTrace() {
                fmt.Printf("%+s:%d\n", f, f)
        }
}

Although the stackTracer interface is not exported by this package, it is considered a part of its stable public interface.

See the documentation for Frame.Format for more details.

Example (StackTrace) 
package main

import (
	"fmt"

	"github.com/jxskiss/errors"
)

func fn() error {
	e1 := errors.New("error")
	e2 := errors.Wrap(e1, "inner")
	e3 := errors.Wrap(e2, "middle")
	return errors.Wrap(e3, "outer")
}

func main() {
	type stackTracer interface {
		StackTrace() errors.StackTrace
	}

	err, ok := errors.Cause(fn()).(stackTracer)
	if !ok {
		panic("oops, err does not implement stackTracer")
	}

	st := err.StackTrace()
	fmt.Printf("%+v", st[0:2]) // top two frames

	// Example output:
	// github.com/jxskiss/errors_test.fn
	//	/home/dfc/src/github.com/jxskiss/errors/example_test.go:47
	// github.com/jxskiss/errors_test.Example_stackTrace
	//	/home/dfc/src/github.com/jxskiss/errors/example_test.go:127
}

Output:

Index

Examples

Constants

This section is empty.

Variables

View Source 
var Annotate = Wrap

Annotate adds a message and ensures there is a stack trace.

View Source 
var Annotatef = Wrapf

Annotatef adds a message and ensures there is a stack trace.

View Source 
var Trace = AddStack

Trace is an alias of AddStack.

Functions

func AddStack added in v0.9.0 

func AddStack(err error) error

AddStack is similar to WithStack. However, it will first check with HasStack to see if a stack trace already exists in the causer chain before creating another one.

func AlreadyExistsf added in v0.11.0 

func AlreadyExistsf(format string, args ...interface{}) error

AlreadyExistsf returns a typed error with " already exists" suffix.

func Append added in v0.12.0 

func Append(err error, errs ...error) error

func As added in v0.14.0 

func As(err error, target interface{}) bool

As finds the first error in err's chain that matches target, and if so, sets target to that error value and returns true.

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.

As will panic if target is not a non-nil pointer to either a type that implements error, or to any interface type. As returns false if err is nil.

func BadRequestf added in v0.9.0 

func BadRequestf(format string, args ...interface{}) error

BadRequestf returns a typed error with " bad request" suffix.

func Cause 

func Cause(err error) error

Cause returns the underlying cause of the error, if possible. An error value has a cause if it implements the following interface: 

type causer interface {
       Cause() error
}

If the error does not implement Cause, the original error will be returned. If the error is nil, nil will be returned without further investigation.

Example 
package main

import (
	"fmt"

	"github.com/jxskiss/errors"
)

func fn() error {
	e1 := errors.New("error")
	e2 := errors.Wrap(e1, "inner")
	e3 := errors.Wrap(e2, "middle")
	return errors.Wrap(e3, "outer")
}

func main() {
	err := fn()
	fmt.Println(err)
	fmt.Println(errors.Cause(err))

}

Output:

outer: middle: inner: error
error
Example (Printf) 
package main

import (
	"fmt"

	"github.com/jxskiss/errors"
)

func main() {
	err := errors.Wrap(func() error {
		return func() error {
			return errors.Errorf("hello %s", fmt.Sprintf("world"))
		}()
	}(), "failed")

	fmt.Printf("%v", err)

}

Output:

failed: hello world

func ErrOrNil added in v0.12.0 

func ErrOrNil(err error) error

func ErrorStack added in v0.9.0 

func ErrorStack(err error) string

ErrorStack will format a stack trace if it is available, otherwise it will be Error() If the error is nil, the empty string is returned Note that this just calls fmt.Sprintf("%+v", err)

func Errorf added in v0.3.0 

func Errorf(format string, args ...interface{}) error

Errorf formats according to a format specifier and returns the string as a value that satisfies error. Errorf also records the stack trace at the point it was called.

Example (Extended) 
package main

import (
	"fmt"

	"github.com/jxskiss/errors"
)

func main() {
	err := errors.Errorf("whoops: %s", "foo")
	fmt.Printf("%+v", err)

	// Example output:
	// whoops: foo
	// github.com/jxskiss/errors_test.ExampleErrorf
	//         /home/dfc/src/github.com/jxskiss/errors/example_test.go:101
	// testing.runExample
	//         /home/dfc/go/src/testing/example.go:114
	// testing.RunExamples
	//         /home/dfc/go/src/testing/example.go:38
	// testing.(*M).Run
	//         /home/dfc/go/src/testing/testing.go:744
	// main.main
	//         /github.com/jxskiss/errors/_test/_testmain.go:102
	// runtime.main
	//         /home/dfc/go/src/runtime/proc.go:183
	// runtime.goexit
	//         /home/dfc/go/src/runtime/asm_amd64.s:2059
}

Output:

func Errors added in v0.10.0 

func Errors(err error) []error

Errors uses the ErrorGroup interface to return a slice of errors. If the ErrorGroup interface is not implemented it returns an array containing just the given error.

func Find added in v0.9.0 

func Find(origErr error, test func(error) bool) error

Find an error in the chain that matches a test function. returns nil if no error is found.

func Forbiddenf added in v0.12.0 

func Forbiddenf(format string, args ...interface{}) error

Forbiddenf returns a typed error with " forbidden" suffix.

func HasStack added in v0.9.0 

func HasStack(err error) bool

HasStack tells whether a StackTracer exists in the error chain

func Is added in v0.14.0 

func Is(err, target error) bool

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.

func IsAlreadyExists added in v0.11.0 

func IsAlreadyExists(err error) bool

IsAlreadyExists reports whether err is an "already exists" error.

func IsBadRequest added in v0.12.0 

func IsBadRequest(err error) bool

IsBadRequest reports whether err is a "bad request" error.

func IsForbidden added in v0.12.0 

func IsForbidden(err error) bool

IsForbidden reports whether err is a "forbidden" error.

func IsMethodNotAllowed added in v0.12.0 

func IsMethodNotAllowed(err error) bool

IsMethodNotAllowed reports whether err is a "method not allowed" error.

func IsNotAssigned added in v0.12.0 

func IsNotAssigned(err error) bool

IsNotAssigned reports whether err is a "not assigned" error.

func IsNotFound added in v0.11.0 

func IsNotFound(err error) bool

IsNotFound reports whether err is a "not found" error.

func IsNotImplemented added in v0.12.0 

func IsNotImplemented(err error) bool

IsNotImplemented reports whether err is a "not implemented" error.

func IsNotProvisioned added in v0.12.0 

func IsNotProvisioned(err error) bool

IsNotProvisioned reports whether err is a "not provisioned" error.

func IsNotSupported added in v0.12.0 

func IsNotSupported(err error) bool

IsNotSupported reports whether err is a "not supported" error.

func IsNotValid added in v0.12.0 

func IsNotValid(err error) bool

IsNotValid reports whether err is a "not valid" error.

func IsNotYetAvailable added in v0.16.0 

func IsNotYetAvailable(err error) bool

IsNotYetAvailable reports whether err is a "not yet available" error.

func IsQuotaLimitExceeded added in v0.16.0 

func IsQuotaLimitExceeded(err error) bool

IsQuotaLimitExceeded reports whether err is a "quota limit exceeded" error.

func IsTimeout added in v0.12.0 

func IsTimeout(err error) bool

IsTimeout reports whether err is a "timeout" error.

func IsUnauthorized added in v0.12.0 

func IsUnauthorized(err error) bool

IsUnauthorized reports whether err is an "unauthorized" error.

func IsUserNotFound added in v0.12.0 

func IsUserNotFound(err error) bool

IsUserNotFound reports whether err is a "user not found" error.

func MethodNotAllowedf added in v0.12.0 

func MethodNotAllowedf(format string, args ...interface{}) error

MethodNotAllowedf returns a typed error with " method not allowed" suffix.

func New 

func New(message string) error

New returns an error with the supplied message. New also records the stack trace at the point it was called.

Example 
package main

import (
	"fmt"

	"github.com/jxskiss/errors"
)

func main() {
	err := errors.New("whoops")
	fmt.Println(err)

}

Output:

whoops
Example (Printf) 
package main

import (
	"fmt"

	"github.com/jxskiss/errors"
)

func main() {
	err := errors.New("whoops")
	fmt.Printf("%+v", err)

	// Example output:
	// whoops
	// github.com/jxskiss/errors_test.ExampleNew_printf
	//         /home/dfc/src/github.com/jxskiss/errors/example_test.go:17
	// testing.runExample
	//         /home/dfc/go/src/testing/example.go:114
	// testing.RunExamples
	//         /home/dfc/go/src/testing/example.go:38
	// testing.(*M).Run
	//         /home/dfc/go/src/testing/testing.go:744
	// main.main
	//         /github.com/jxskiss/errors/_test/_testmain.go:106
	// runtime.main
	//         /home/dfc/go/src/runtime/proc.go:183
	// runtime.goexit
	//         /home/dfc/go/src/runtime/asm_amd64.s:2059
}

Output:

func NotAssignedf added in v0.12.0 

func NotAssignedf(format string, args ...interface{}) error

NotAssignedf returns a typed error with " not assigned" suffix.

func NotFoundf added in v0.9.0 

func NotFoundf(format string, args ...interface{}) error

NotFoundf returns a typed error with " not found" suffix.

func NotImplementedf added in v0.12.0 

func NotImplementedf(format string, args ...interface{}) error

NotImplementedf returns a typed error with " not implemented" suffix.

func NotProvisionedf added in v0.12.0 

func NotProvisionedf(format string, args ...interface{}) error

NotProvisionedf returns a typed error with " not provisioned" suffix.

func NotSupportedf added in v0.9.0 

func NotSupportedf(format string, args ...interface{}) error

NotSupportedf returns a typed error with " not supported" suffix.

func NotValidf added in v0.11.0 

func NotValidf(format string, args ...interface{}) error

NotValidf returns a typed error with " not valid" suffix.

func NotYetAvailablef added in v0.16.0 

func NotYetAvailablef(format string, args ...interface{}) error

NotYetAvailablef returns a typed error with " not yet available" suffix.

func QuotaLimitExceededf added in v0.16.0 

func QuotaLimitExceededf(format string, args ...interface{}) error

QuotaLimitExceededf returns a typed error with " quota limit exceeded" suffix.

func Timeoutf added in v0.12.0 

func Timeoutf(format string, args ...interface{}) error

Timeoutf returns a typed error with " timeout" suffix.

func Unauthorizedf added in v0.12.0 

func Unauthorizedf(format string, args ...interface{}) error

Unauthorizedf returns a typed error with " unauthorized" suffix.

func Unwrap added in v0.9.0 

func Unwrap(err error) error

Unwrap returns the next error in the chain if it implements the causer interface, this goes one-level deeper, whereas Cause goes as far as possible.

If the err does not implements the causer interface, this function behaves like the Unwrap function from standard errors library in go1.13+.

func UserNotFoundf added in v0.12.0 

func UserNotFoundf(format string, args ...interface{}) error

UserNotFoundf returns a typed error with " user not found" suffix.

func WalkDeep added in v0.9.0 

func WalkDeep(err error, visitor func(err error) bool) bool

WalkDeep does a depth-first traversal of all errors. Any ErrorGroup is traversed (after going deep). The visitor function can return true to end the traversal early In that case, WalkDeep will return true, otherwise false.

func WithMessage added in v0.8.0 

func WithMessage(err error, message string) error

WithMessage annotates err with a new message. If err is nil, WithMessage returns nil.

Example 
package main

import (
	"fmt"

	"github.com/jxskiss/errors"
)

func main() {
	cause := errors.New("whoops")
	err := errors.WithMessage(cause, "oh noes")
	fmt.Println(err)

}

Output:

oh noes: whoops

func WithMessagef added in v0.12.0 

func WithMessagef(err error, format string, args ...interface{}) error

WithMessagef annotates err with the format specifier. If err is nil, WithMessagef returns nil.

func WithStack added in v0.8.0 

func WithStack(err error) error

WithStack annotates err with a stack trace at the point WithStack was called. If err is nil, WithStack returns nil.

For most use cases this is deprecated and AddStack should be used (which will ensure just one stack trace). However, one may want to use this in some situations, for example to create a 2nd trace across a goroutine.

Example 
package main

import (
	"fmt"

	"github.com/jxskiss/errors"
)

func main() {
	cause := errors.New("whoops")
	err := errors.WithStack(cause)
	fmt.Println(err)

}

Output:

whoops
Example (Printf) 
package main

import (
	"fmt"

	"github.com/jxskiss/errors"
)

func main() {
	cause := errors.New("whoops")
	err := errors.WithStack(cause)
	fmt.Printf("%+v", err)

	// Example Output:
	// whoops
	// github.com/jxskiss/errors_test.ExampleWithStack_printf
	//         /home/fabstu/go/src/github.com/jxskiss/errors/example_test.go:55
	// testing.runExample
	//         /usr/lib/go/src/testing/example.go:114
	// testing.RunExamples
	//         /usr/lib/go/src/testing/example.go:38
	// testing.(*M).Run
	//         /usr/lib/go/src/testing/testing.go:744
	// main.main
	//         github.com/jxskiss/errors/_test/_testmain.go:106
	// runtime.main
	//         /usr/lib/go/src/runtime/proc.go:183
	// runtime.goexit
	//         /usr/lib/go/src/runtime/asm_amd64.s:2086
	// github.com/jxskiss/errors_test.ExampleWithStack_printf
	//         /home/fabstu/go/src/github.com/jxskiss/errors/example_test.go:56
	// testing.runExample
	//         /usr/lib/go/src/testing/example.go:114
	// testing.RunExamples
	//         /usr/lib/go/src/testing/example.go:38
	// testing.(*M).Run
	//         /usr/lib/go/src/testing/testing.go:744
	// main.main
	//         github.com/jxskiss/errors/_test/_testmain.go:106
	// runtime.main
	//         /usr/lib/go/src/runtime/proc.go:183
	// runtime.goexit
	//         /usr/lib/go/src/runtime/asm_amd64.s:2086
}

Output:

func Wrap 

func Wrap(err error, message string) error

Wrap returns an error annotating err with a stack trace at the point Wrap is called, and the supplied message. If err is nil, Wrap returns nil.

Example 
package main

import (
	"fmt"

	"github.com/jxskiss/errors"
)

func main() {
	cause := errors.New("whoops")
	err := errors.Wrap(cause, "oh noes")
	fmt.Println(err)

}

Output:

oh noes: whoops
Example (Extended) 
package main

import (
	"fmt"

	"github.com/jxskiss/errors"
)

func fn() error {
	e1 := errors.New("error")
	e2 := errors.Wrap(e1, "inner")
	e3 := errors.Wrap(e2, "middle")
	return errors.Wrap(e3, "outer")
}

func main() {
	err := fn()
	fmt.Printf("%+v\n", err)

	// Example output:
	// error
	// github.com/jxskiss/errors_test.fn
	//         /home/dfc/src/github.com/jxskiss/errors/example_test.go:47
	// github.com/jxskiss/errors_test.ExampleCause_printf
	//         /home/dfc/src/github.com/jxskiss/errors/example_test.go:63
	// testing.runExample
	//         /home/dfc/go/src/testing/example.go:114
	// testing.RunExamples
	//         /home/dfc/go/src/testing/example.go:38
	// testing.(*M).Run
	//         /home/dfc/go/src/testing/testing.go:744
	// main.main
	//         /github.com/jxskiss/errors/_test/_testmain.go:104
	// runtime.main
	//         /home/dfc/go/src/runtime/proc.go:183
	// runtime.goexit
	//         /home/dfc/go/src/runtime/asm_amd64.s:2059
	// github.com/jxskiss/errors_test.fn
	// 	  /home/dfc/src/github.com/jxskiss/errors/example_test.go:48: inner
	// github.com/jxskiss/errors_test.fn
	//        /home/dfc/src/github.com/jxskiss/errors/example_test.go:49: middle
	// github.com/jxskiss/errors_test.fn
	//      /home/dfc/src/github.com/jxskiss/errors/example_test.go:50: outer
}

Output:

func Wrapf added in v0.2.0 

func Wrapf(err error, format string, args ...interface{}) error

Wrapf returns an error annotating err with a stack trace at the point Wrapf is called, and the format specifier. If err is nil, Wrapf returns nil.

Example 
package main

import (
	"fmt"

	"github.com/jxskiss/errors"
)

func main() {
	cause := errors.New("whoops")
	err := errors.Wrapf(cause, "oh noes #%d", 2)
	fmt.Println(err)

}

Output:

oh noes #2: whoops

Types

type ErrorGroup added in v0.9.0 

type ErrorGroup interface {
	Errors() []error
}

ErrorGroup is an interface for multiple errors that are not a chain. This happens for example when executing multiple operations in parallel.

type Frame added in v0.6.0 

type Frame = pkgerr.Frame

type MultiError added in v0.12.0 

type MultiError []error

MultiError wraps a slice of errors and implements the error interface. This can be used to collect a bunch of errors (such as during form validation) and then return them all together as a single error.

func (MultiError) Error added in v0.12.0 

func (E MultiError) Error() string

func (MultiError) Errors added in v0.12.0 

func (E MultiError) Errors() []error

func (MultiError) Format added in v0.12.0 

func (E MultiError) Format(f fmt.State, c rune)

type SizedErrors added in v0.15.0 

type SizedErrors struct {
	// contains filtered or unexported fields
}

func NewSizedErrors added in v0.16.0 

func NewSizedErrors(size int) *SizedErrors

func (*SizedErrors) Append added in v0.15.0 

func (E *SizedErrors) Append(errs ...error)

func (*SizedErrors) Error added in v0.15.0 

func (E *SizedErrors) Error() string

func (*SizedErrors) Errors added in v0.15.0 

func (E *SizedErrors) Errors() (errors []error)

Errors returns the errors as a slice in reversed order, if the underlying errors are more than size, only size errors will be returned, plus an additional error indicates the omitted error count.

func (*SizedErrors) Format added in v0.15.0 

func (E *SizedErrors) Format(f fmt.State, c rune)

type StackTrace added in v0.7.0 

type StackTrace = pkgerr.StackTrace

type StackTracer added in v0.9.0 

type StackTracer interface {
	StackTrace() StackTrace
}

StackTracer retrieves the StackTrace Generally you would want to use the GetStackTracer function to do that.

func GetStackTracer added in v0.9.0 

func GetStackTracer(origErr error) StackTracer

GetStackTracer will return the first StackTracer in the causer chain. This function is used by AddStack to avoid creating redundant stack traces.

You can also use the StackTracer interface on the returned error to get the stack trace.

func NewStack added in v0.9.0 

func NewStack(skip int) StackTracer

NewStack is for library implementers that want to generate a stack trace. Normally you should insted use AddStack to get an error with a stack trace.

The result of this function can be turned into a stack trace by calling .StackTrace()

This function takes an argument for the number of stack frames to skip. This avoids putting stack generation function calls like this one in the stack trace. A value of 0 will give you the line that called NewStack(0) A library author wrapping this in their own function will want to use a value of at least 1.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.