errors

Documentation

Overview

The errors package provides a way to create and diagnose errors. It is compatible with the usual Go error idioms but adds a way to wrap errors so that they record source location information while retaining a consistent way for code to inspect errors to find out particular problems.

An error created by this package holds three values, any one of which (but not all) may be zero

• an error message. This is used as part of the result of the Error method.
• an underlying error. This holds the error that the error was created in response to.
• an error cause. See below.

Error Causes

The "cause" of an error is something that code can use to diagnose what an error means and take action accordingly.

For example, if you use os.Remove to remove a file that is not there, it returns an error with a cause that satisfies os.IsNotExist. If you use filepath.Match to try to match a malformed pattern, it returns an error with a cause that equals filepath.ErrBadPattern.

When the errors package wraps an error value with another one, the new error hides the cause by default. This is to prevent unintended dependencies between unrelated parts of the code base. When the cause is hidden, a caller can't write code that relies on the type or value of a particular cause which may well only be an implementation detail and subject to future change - a potentially API-breaking change if the cause is not hidden.

The Note function can be used to preserve an existing error cause. The Because function can be used to associate an error with an existing cause value.

Error wrapping

When an error is returned that "wraps" another one, the new error records the source code location of the caller. This means that it is possible to extract this information later (by calling Details, for example). It is good practice to wrap errors whenever returning an error returned by a lower level function, so that the path taken by the error is recorded. This can make debugging significantly easier when there are many places an error could have come from.

Index

• func Any(error) bool
• func Because(err, cause error, msg string) error
• func Cause(err error) error
• func Details(err error) string
• func Is(err error) func(error) bool
• func New(s string) error
• func Note(err error, shouldPreserveCause func(error) bool, msg string) error
• func OneOf(predicates ...func(error) bool) func(error) bool
• func SetLocation(err error, callDepth int)
• func Wrap(err error) error
• type Causer
• type Locationer
• type Locator
• type Wrapper

Functions

func Any

func Any(error) bool

Any returns true. It can be used as an argument to Note to allow any cause to pass through to the wrapped error.

func Because

func Because(err, cause error, msg string) error

Because returns a new error that wraps err and has the given cause, and adds the given message.

If err is nil and msg is empty, the returned error's message will be the same as cause's. This is equivalent to calling errors.Note(cause, errors.Is(cause), "") and is useful for annotating an global error value with source location information.

Because returns a nil error if all of err, cause and msg are zero.

func Cause

func Cause(err error) error

Cause returns the cause of the given error. If err does not implement Causer or its Cause method returns nil, it returns err itself.

Cause is the usual way to diagnose errors that may have been wrapped.

func Details

func Details(err error) string

Details returns information about the stack of underlying errors wrapped by err, in the format:

[
	{filename:99: error one}
	{otherfile:55: cause of error one}
]

The details are found by type-asserting the error to the Locator, Causer and Wrapper interfaces. Details of the underlying stack are found by recursively calling Underlying when the underlying error implements Wrapper.

func Is

func Is(err error) func(error) bool

Is returns a function that returns whether the an error is equal to the given error. It is intended to be used as a "shouldPreserveCause" argument to Note. For example:

return errgo.Note(err, errgo.Is(http.ErrNoCookie), "")

would return an error with an http.ErrNoCookie cause only if that was err's cause.

func New

func New(s string) error

New returns a new error with the given error message and no cause. It is a drop-in replacement for errors.New from the standard library.

func Note

func Note(err error, shouldPreserveCause func(error) bool, msg string) error

Note returns a new error that wraps the given error. It preserves the cause if shouldPreserveCause is non-nil and shouldPreserveCause(err) is true. If msg is non-empty, it is used to prefix the returned error's Error value.

If err is nil, Note returns nil and does not call shouldPreserveCause.

func OneOf

func OneOf(predicates ...func(error) bool) func(error) bool

OneOf returns a function suitable for passing to Note that reports whether an error matches any of the given predicates.

func SetLocation

func SetLocation(err error, callDepth int)

SetLocation sets the location of the error to the file and line number of the code that is running callDepth frames above the caller. It does nothing if the error was not created by this package. SetLocation should only be called immediately after an error has been created, before it is shared with other code which could access it concurrently.

This function is helpful when a helper function is used to create an error and the caller of the helper function is the important thing, not the location in the helper function itself.

func Wrap

func Wrap(err error) error

Wrap returns a new error that wraps the given error and holds information about the caller. It is equivalent to Note(err, nil, ""). Note that this means that the returned error has no cause.

Types

type Causer

type Causer interface {
	Cause() error
}

Causer is the type of an error that may provide an error cause for error diagnosis. Cause may return nil if there is no cause (for example because the cause has been masked).

type Locationer

type Locationer = Locator

Deprecated: Locationer is the old name for Locator, kept for backward compatibility only.

type Locator

type Locator interface {
	// Location returns the name of the file and the line number
	// associated with an error.
	Location() (file string, line int)
}

Locator can be implemented by any error type that wants to expose the source location of an error.

type Wrapper

type Wrapper interface {
	// Message returns the top level error message,
	// not including the message from the underlying
	// error.
	Message() string

	// Underlying returns the underlying error, or nil
	// if there is none.
	Underlying() error
}

Wrapper is the type of an error that wraps another error. It is exposed so that external types may implement it, but should in general not be used otherwise.