https://github.com/go-coldbrew/errors
Enhanced Go errors with stack traces, gRPC status codes, and async error notification (Sentry/Rollbar/Airbrake)
https://github.com/go-coldbrew/errors
coldbrew error-handling errors go golang grpc sentry stack-trace stacktrace
Last synced: 6 days ago
JSON representation
Enhanced Go errors with stack traces, gRPC status codes, and async error notification (Sentry/Rollbar/Airbrake)
- Host: GitHub
- URL: https://github.com/go-coldbrew/errors
- Owner: go-coldbrew
- License: apache-2.0
- Created: 2021-01-09T11:23:56.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2026-03-28T09:11:54.000Z (11 days ago)
- Last Synced: 2026-03-28T09:37:29.464Z (11 days ago)
- Topics: coldbrew, error-handling, errors, go, golang, grpc, sentry, stack-trace, stacktrace
- Language: Go
- Homepage: https://docs.coldbrew.cloud
- Size: 387 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/go-coldbrew/errors/actions/workflows/go.yml)
[](https://goreportcard.com/report/github.com/go-coldbrew/errors)
[](https://pkg.go.dev/github.com/go-coldbrew/errors)
[](https://opensource.org/licenses/MIT)
# errors
```go
import "github.com/go-coldbrew/errors"
```
Package errors provides an implementation of golang error with stack strace information attached to it, the error objects created by this package are compatible with https://golang.org/pkg/errors/
How To Use 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.
```
if you want to create a new error use New
if you want to skip some functions on the stack use NewWithSkip
if you want to add GRPC status use NewWithStatus
if you want to skip some functions on the stack and add GRPC status use NewWithSkipAndStatus
if you want to wrap an existing error use Wrap
if you want to wrap an existing error and add GRPC status use WrapWithStatus
if you want to wrap an existing error and skip some functions on the stack use WrapWithSkip
if you want to wrap an existing error, skip some functions on the stack and add GRPC status use WrapWithSkipAndStatus
if you want to wrap an existing error and add notifier options use WrapWithNotifier
if you want to wrap an existing error, skip some functions on the stack and add notifier options use WrapWithSkipAndNotifier
```
Head to https://docs.coldbrew.cloud for more information.
Example (Cause)
Cause returns the root cause of a wrapped error chain.
```go
package main
import (
"fmt"
"io"
"github.com/go-coldbrew/errors"
)
func main() {
root := io.EOF
first := 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)
```go
package main
import (
"fmt"
"github.com/go-coldbrew/errors"
)
func main() {
err := errors.New("something failed")
frames := err.StackFrame()
// Stack frames are captured automatically
fmt.Println(len(frames) > 0)
}
```
#### Output
```
true
```
## Index
- [Constants](<#constants>)
- [func SetBaseFilePath\(path string\)](<#SetBaseFilePath>)
- [func SetMaxStackDepth\(n int\)](<#SetMaxStackDepth>)
- [type ErrorExt](<#ErrorExt>)
- [func New\(msg string\) ErrorExt](<#New>)
- [func NewWithSkip\(msg string, skip int\) ErrorExt](<#NewWithSkip>)
- [func NewWithSkipAndStatus\(msg string, skip int, status \*grpcstatus.Status\) ErrorExt](<#NewWithSkipAndStatus>)
- [func NewWithStatus\(msg string, status \*grpcstatus.Status\) ErrorExt](<#NewWithStatus>)
- [func Newf\(format string, args ...any\) ErrorExt](<#Newf>)
- [func Wrap\(err error, msg string\) ErrorExt](<#Wrap>)
- [func WrapWithSkip\(err error, msg string, skip int\) ErrorExt](<#WrapWithSkip>)
- [func WrapWithSkipAndStatus\(err error, msg string, skip int, status \*grpcstatus.Status\) ErrorExt](<#WrapWithSkipAndStatus>)
- [func WrapWithStatus\(err error, msg string, status \*grpcstatus.Status\) ErrorExt](<#WrapWithStatus>)
- [func Wrapf\(err error, format string, args ...any\) ErrorExt](<#Wrapf>)
- [type NotifyExt](<#NotifyExt>)
- [type StackFrame](<#StackFrame>)
## Constants
SupportPackageIsVersion1 is a compile\-time assertion constant. Downstream packages reference this to enforce version compatibility.
```go
const SupportPackageIsVersion1 = true
```
```go
func SetBaseFilePath(path string)
```
SetBaseFilePath sets the base file path for linking source code with reported stack information
```go
func SetMaxStackDepth(n int)
```
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.
ErrorExt is the interface that defines a error, any ErrorExt implementors can use and override errors and notifier package
```go
type ErrorExt interface {
// Callers returns the call poiners for the stack
Callers() []uintptr
// StackFrame returns the stack frame for the error
StackFrame() []StackFrame
//Cause returns the original error object that caused this error
Cause() error
//GRPCStatus allows ErrorExt to be treated as a GRPC Error
GRPCStatus() *grpcstatus.Status
// contains filtered or unexported methods
}
```
```go
func New(msg string) ErrorExt
```
New creates a new error with stack information
Example
```go
package main
import (
"fmt"
"github.com/go-coldbrew/errors"
)
func main() {
err := errors.New("something went wrong")
fmt.Println(err)
}
```
#### Output
```
something went wrong
```
```go
func NewWithSkip(msg string, skip int) ErrorExt
```
NewWithSkip creates a new error skipping the number of function on the stack
### func [NewWithSkipAndStatus]()
```go
func NewWithSkipAndStatus(msg string, skip int, status *grpcstatus.Status) ErrorExt
```
NewWithSkipAndStatus creates a new error skipping the number of function on the stack and GRPC status
```go
func NewWithStatus(msg string, status *grpcstatus.Status) ErrorExt
```
NewWithStatus creates a new error with statck information and GRPC status
```go
func Newf(format string, args ...any) ErrorExt
```
Newf creates a new error with a formatted message and stack information
Example
```go
package main
import (
"fmt"
"github.com/go-coldbrew/errors"
)
func main() {
err := errors.Newf("user %s not found", "alice")
fmt.Println(err)
}
```
#### Output
```
user alice not found
```
```go
func Wrap(err error, msg string) ErrorExt
```
Wrap wraps an existing error and appends stack information if it does not exists
Example
```go
package main
import (
"fmt"
"io"
"github.com/go-coldbrew/errors"
)
func main() {
original := io.EOF
wrapped := 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 stdlib errors.Is for unwrapping.
```go
package main
import (
stderrors "errors"
"fmt"
"io"
"github.com/go-coldbrew/errors"
)
func main() {
original := io.EOF
wrapped := errors.Wrap(original, "read failed")
fmt.Println(stderrors.Is(wrapped, io.EOF))
}
```
#### Output
```
true
```
```go
func WrapWithSkip(err error, msg string, skip int) 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]()
```go
func WrapWithSkipAndStatus(err error, msg string, skip int, 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
```go
func WrapWithStatus(err error, msg string, 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.
```go
package main
import (
"fmt"
"github.com/go-coldbrew/errors"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/status"
)
func main() {
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
```
```go
func Wrapf(err error, format string, args ...any) ErrorExt
```
Wrapf wraps an existing error with a formatted message and appends stack information if it does not exist
Example
```go
package main
import (
"fmt"
"github.com/go-coldbrew/errors"
)
func main() {
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
```
NotifyExt is the interface definition for notifier related options
```go
type NotifyExt interface {
// ShouldNotify returns true if the error should be notified
ShouldNotify() bool
// Notified sets the error to be notified or not
Notified(status bool)
}
```
StackFrame represents the stackframe for tracing exception
```go
type StackFrame struct {
File string `json:"file"`
Line int `json:"line"`
Func string `json:"function"`
}
```
Generated by [gomarkdoc]()