pkg/errors
Errors
pkg/errors is a Go library that provides primitives for creating, annotating, and inspecting errors with stack traces and contextual information. Its core identity centers on capturing the call stack at the point of error creation or wrapping, preserving that information for later debugging and root cause analysis.
The library distinguishes itself through a set of tightly integrated capabilities for error handling. It supports wrapping errors with descriptive messages while recording a new stack trace at the wrapping point, annotating existing errors with either a message or a stack trace independently, and creating new errors that automatically capture the call stack. For inspection, it provides mechanisms to walk the wrapped error chain to retrieve the root underlying cause or to search through the chain for an error matching a specific type or value.
Error formatting is handled through Go's standard formatting verbs, allowing developers to conditionally print stack trace details alongside error messages for diagnostic purposes. The library's design forms a linked chain of wrapped errors, enabling traversal from the outermost context down to the original error.
Features
- Stack Trace Capture - Captures the call stack at the point of error creation or wrapping for later inspection.
- Stack Trace Creators - Creates new error values that record the stack trace at the point of creation.
- Chain Type Matchers - Searches through the error chain to find the first error matching a target type or value.
- Error Wrapping - Wraps errors with descriptive messages while preserving the original error for chain traversal.
- Chain Inspectors - Searches through wrapped error chains to find matching errors or retrieve the root cause.
- Stack Trace Wrappers - Records stack traces at error creation and wrapping points for debugging.
- Error Cause Mapping - Provides a function to unwrap the error chain and retrieve the root underlying cause.
- Stack Trace Annotators - Adds a stack trace to an existing error without adding a new message.
- Stack Trace Formatters - Prints errors with optional detailed stack trace information using standard formatting verbs.
- Message Annotators - Adds a descriptive message to an existing error without recording a new stack trace.
- Format Verb Stack Printers - Ships error formatting that prints stack traces conditionally via Go's fmt formatting verbs.
- Format Verb Stack Printers - Prints detailed stack trace information using standard formatting verbs.
- Error Handling - Simplifies error handling and wrapping.
