errors

import"github.com/go-coldbrew/errors"

Package errors is a drop-in replacement for the standard library "errors" package that adds stack trace capture, gRPC status codes, and error notification support.

The following standard library helpers are re-exported: Is, As, Unwrap, Join, and the ErrUnsupported sentinel. This allows you to use this package as your sole errors import:

import "github.com/go-coldbrew/errors"
// Standard library functions work as expected:
errors.Is(err, target)
errors.As(err, &target)
errors.Unwrap(err)
errors.Join(err1, err2)
// ColdBrew extensions add stack traces and gRPC status:
errors.New("something failed") // captures stack trace
errors.Wrap(err, "context") // wraps with stack trace
errors.Cause(err) // walks Unwrap chain to root cause

Error Creation

The simplest way to use this package is by calling one of the two functions:

errors.New(...)
errors.Wrap(...)

You can also initialize custom error stack by using one of the WithSkip functions. WithSkip allows skipping the defined number of functions from the stack information.

New — create a new error with stack info
NewWithSkip — skip functions on the stack
NewWithStatus — add GRPC status
NewWithSkipAndStatus — skip functions and add GRPC status
Wrap — wrap an existing error
WrapWithStatus — wrap and add GRPC status
WrapWithSkip — wrap and skip functions on the stack
WrapWithSkipAndStatus — wrap, skip functions, and add GRPC status

Head to https://docs.coldbrew.cloud for more information.

Example (Cause)

Cause returns the root cause of a wrapped error chain.

package main
import (
"fmt""io""github.com/go-coldbrew/errors"
)
funcmain() {
root:=io.EOFfirst:=errors.Wrap(root, "read body")
second:=errors.Wrap(first, "handle request")
fmt.Println("error:", second)
fmt.Println("cause:", second.Cause())
}

Output

error: handle request: read body: EOF
cause: EOF

Example (Stack Frame)

package main
import (
"fmt""github.com/go-coldbrew/errors"
)
funcmain() {
err:=errors.New("something failed")
frames:=err.StackFrame()
// Stack frames are captured automaticallyfmt.Println(len(frames) >0)
}

Output

true

Index

• Constants
• Variables
• func As(err error, target any) bool
• func AsType[E error](err error) (E, bool)
• func Cause(err error) error
• func Is(err, target error) bool
• func Join(errs ...error) error
• func SetBaseFilePath(path string)
• func SetMaxStackDepth(n int)
• func Unwrap(err error) error
• type ErrorExt
  • func New(msg string) ErrorExt
  • func NewWithSkip(msg string, skip int) ErrorExt
  • func NewWithSkipAndStatus(msg string, skip int, status *grpcstatus.Status) ErrorExt
  • func NewWithStatus(msg string, status *grpcstatus.Status) ErrorExt
  • func Newf(format string, args ...any) ErrorExt
  • func Wrap(err error, msg string) ErrorExt
  • func WrapWithSkip(err error, msg string, skip int) ErrorExt
  • func WrapWithSkipAndStatus(err error, msg string, skip int, status *grpcstatus.Status) ErrorExt
  • func WrapWithStatus(err error, msg string, status *grpcstatus.Status) ErrorExt
  • func Wrapf(err error, format string, args ...any) ErrorExt
• type NotifyExt
• type StackFrame

Constants

SupportPackageIsVersion1 is a compile-time assertion constant. Downstream packages reference this to enforce version compatibility.

constSupportPackageIsVersion1=true

Variables

ErrUnsupported indicates that a requested operation cannot be performed, because it is unsupported.

Re-exported from the standard library errors package.

varErrUnsupported=stderrors.ErrUnsupported

func As

funcAs(errerror, targetany) bool

As finds the first error in err's tree that matches target, and if one is found, sets target to that error value and returns true.

Re-exported from the standard library errors package.

Example

package main
import (
"fmt""github.com/go-coldbrew/errors""google.golang.org/grpc/codes""google.golang.org/grpc/status"
)
funcmain() {
grpcErr:=errors.NewWithStatus("not found", status.New(codes.NotFound, "not found"))
wrapped:=errors.Wrap(grpcErr, "lookup failed")
varext errors.ErrorExtiferrors.As(wrapped, &ext) {
fmt.Println("found ErrorExt:", ext.GRPCStatus().Code())
}
}

Output

found ErrorExt: NotFound

func AsType

funcAsType[Eerror](errerror) (E, bool)

AsType finds the first error in err's tree that matches the type E, and if one is found, returns that error value and true. Otherwise, it returns the zero value of E and false.

Re-exported from the standard library errors package (requires Go 1.26+).

func Cause

funcCause(errerror) error

Cause walks the Unwrap chain of err and returns the innermost (root cause) error. If err does not implement Unwrap, err itself is returned. If err is nil, nil is returned.

For ErrorExt errors, this produces the same result as calling the Cause method, but this function works on any error that implements the standard Unwrap interface.

Note: for multi-errors (errors implementing Unwrap() []error, such as those created by Join), the single-error Unwrap returns nil, so Cause returns the multi-error itself.

Example

package main
import (
"fmt""io""github.com/go-coldbrew/errors"
)
funcmain() {
root:=io.EOFfirst:=errors.Wrap(root, "read body")
second:=errors.Wrap(first, "handle request")
fmt.Println(errors.Cause(second))
}

Output

EOF

func Is

funcIs(err, targeterror) bool

Is reports whether any error in err's tree matches target.

An error is considered a match if it is equal to the target or if it implements an Is(error) bool method such that Is(target) returns true.

Re-exported from the standard library errors package.

Example

package main
import (
"fmt""github.com/go-coldbrew/errors"
)
funcmain() {
base:=fmt.Errorf("connection refused")
wrapped:=errors.Wrap(base, "dial failed")
fmt.Println(errors.Is(wrapped, base))
}

Output

true

func Join

funcJoin(errs...error) error

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.

Re-exported from the standard library errors package.

Example

package main
import (
"fmt""github.com/go-coldbrew/errors"
)
funcmain() {
err1:=errors.New("first")
err2:=errors.New("second")
joined:=errors.Join(err1, err2)
fmt.Println(errors.Is(joined, err1))
fmt.Println(errors.Is(joined, err2))
}

Output

true
true

func SetBaseFilePath

funcSetBaseFilePath(pathstring)

SetBaseFilePath sets the base file path for linking source code with reported stack information

func SetMaxStackDepth

funcSetMaxStackDepth(nint)

SetMaxStackDepth sets the maximum number of stack frames captured when creating errors. Accepts values in [1, 256]; out-of-range values are ignored. Default is 16. Safe for concurrent use.

func Unwrap

funcUnwrap(errerror) error

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.

Re-exported from the standard library errors package.

Example

package main
import (
"fmt""io""github.com/go-coldbrew/errors"
)
funcmain() {
base:=io.EOFwrapped:=errors.Wrap(base, "read failed")
fmt.Println(errors.Unwrap(wrapped))
}

Output

EOF

type ErrorExt

ErrorExt is the interface that defines a error, any ErrorExt implementors can use and override errors and notifier package

typeErrorExtinterface {
// Callers returns the call poiners for the stackCallers() []uintptr// StackFrame returns the stack frame for the errorStackFrame() []StackFrame//Cause returns the original error object that caused this errorCause() error//GRPCStatus allows ErrorExt to be treated as a GRPC ErrorGRPCStatus() *grpcstatus.Status// contains filtered or unexported methods
}

func New

funcNew(msgstring) ErrorExt

New creates a new error with stack information

Example

package main
import (
"fmt""github.com/go-coldbrew/errors"
)
funcmain() {
err:=errors.New("something went wrong")
fmt.Println(err)
}

Output

something went wrong

func NewWithSkip

funcNewWithSkip(msgstring, skipint) ErrorExt

NewWithSkip creates a new error skipping the number of function on the stack

func NewWithSkipAndStatus

funcNewWithSkipAndStatus(msgstring, skipint, status*grpcstatus.Status) ErrorExt

NewWithSkipAndStatus creates a new error skipping the number of function on the stack and GRPC status

func NewWithStatus

funcNewWithStatus(msgstring, status*grpcstatus.Status) ErrorExt

NewWithStatus creates a new error with statck information and GRPC status

func Newf

funcNewf(formatstring, args...any) ErrorExt

Newf creates a new error with a formatted message and stack information

Example

package main
import (
"fmt""github.com/go-coldbrew/errors"
)
funcmain() {
err:=errors.Newf("user %s not found", "alice")
fmt.Println(err)
}

Output

user alice not found

func Wrap

funcWrap(errerror, msgstring) ErrorExt

Wrap wraps an existing error and appends stack information if it does not exists

Example

package main
import (
"fmt""io""github.com/go-coldbrew/errors"
)
funcmain() {
original:=io.EOFwrapped:=errors.Wrap(original, "failed to read config")
fmt.Println(wrapped)
fmt.Println("cause:", wrapped.Cause())
}

Output

failed to read config: EOF
cause: EOF

Example (Errors Is)

Wrapped errors are compatible with errors.Is for unwrapping. No separate "errors" import needed — Is is re-exported.

package main
import (
"fmt""io""github.com/go-coldbrew/errors"
)
funcmain() {
original:=io.EOFwrapped:=errors.Wrap(original, "read failed")
fmt.Println(errors.Is(wrapped, io.EOF))
}

Output

true

func WrapWithSkip

funcWrapWithSkip(errerror, msgstring, skipint) ErrorExt

WrapWithSkip wraps an existing error and appends stack information if it does not exists skipping the number of function on the stack

func WrapWithSkipAndStatus

funcWrapWithSkipAndStatus(errerror, msgstring, skipint, status*grpcstatus.Status) ErrorExt

WrapWithSkip wraps an existing error and appends stack information if it does not exists skipping the number of function on the stack along with GRPC status

func WrapWithStatus

funcWrapWithStatus(errerror, msgstring, status*grpcstatus.Status) ErrorExt

Wrap wraps an existing error and appends stack information if it does not exists along with GRPC status

Example

WrapWithStatus attaches a gRPC status code to a wrapped error.

package main
import (
"fmt""github.com/go-coldbrew/errors""google.golang.org/grpc/codes""google.golang.org/grpc/status"
)
funcmain() {
original:=fmt.Errorf("record not found")
s:=status.New(codes.NotFound, "user not found")
wrapped:=errors.WrapWithStatus(original, "lookup failed", s)
fmt.Println(wrapped)
fmt.Println("gRPC code:", wrapped.GRPCStatus().Code())
}

Output

lookup failed: record not found
gRPC code: NotFound

func Wrapf

funcWrapf(errerror, formatstring, args...any) ErrorExt

Wrapf wraps an existing error with a formatted message and appends stack information if it does not exist

Example

package main
import (
"fmt""github.com/go-coldbrew/errors"
)
funcmain() {
err:=fmt.Errorf("connection refused")
wrapped:=errors.Wrapf(err, "failed to connect to port %d", 5432)
fmt.Println(wrapped)
}

Output

failed to connect to port 5432: connection refused

type NotifyExt

NotifyExt is the interface definition for notifier related options

typeNotifyExtinterface {
// ShouldNotify returns true if the error should be notifiedShouldNotify() bool// Notified sets the error to be notified or notNotified(statusbool)
}

type StackFrame

StackFrame represents the stackframe for tracing exception

typeStackFramestruct {
Filestring`json:"file"`Lineint`json:"line"`Funcstring`json:"function"`
}

Generated by gomarkdoc