cockroachdb/errors

cockroachdb/errors is a Go error-handling library built to be a drop-in replacement for both the standard library’s errors package and github.com/pkg/errors. On top of familiar constructors like New, Wrap, and Errorf, it adds features aimed at distributed systems: errors can be encoded to protobuf and decoded on a different node or a different software version, while still working correctly with errors.Is() and errors.As() across that network boundary.

The library also separates PII-free “safe” details from unsafe message content, so errors can be reported to Sentry.io automatically without leaking sensitive data. It supports composable wrapper types for hints, structured details, assertion failures, issue-tracker links, secondary causes, and context tags, all built around a stable leaf/wrapper encode-decode registry that lets unknown error types degrade gracefully instead of breaking cross-version compatibility.

What You Get

• Drop-in New, Newf, Wrap, Wrapf, Errorf, and Join constructors compatible with stdlib errors and pkg/errors call sites
• Protobuf-based EncodeError/DecodeError so error objects survive gRPC/network transport across mixed software versions
• A safe-details system (GetSafeDetails, WithSafeDetails) that separates PII-free strings for Sentry reporting from user-facing messages
• Composable wrapper types: hints (WithHint), structured details (WithDetail), assertion failures (AssertionFailedf), issue-tracker links (WithIssueLink), and secondary causes (WithSecondaryError)
• A pluggable leaf/wrapper encoder-decoder registry (RegisterLeafEncoder/RegisterLeafDecoder) so custom error types remain decodable even when the receiving binary doesn’t know the type
• Built-in gRPC and HTTP integration packages (extgrpc, exthttp) plus a oserror subpackage that peeks through wrapping for os.IsPermission/IsTimeout/IsExist/IsNotExist-style checks

Common Use Cases

• Distributed databases and services where an error raised on one node must be correctly identified (errors.Is) after crossing an RPC boundary to a different node running a different binary version
• Applications that need automatic, PII-safe Sentry error reporting without hand-writing redaction logic at every call site
• Codebases migrating off github.com/pkg/errors that want stack traces and Cause()/Unwrap() compatibility without rewriting call sites
• Systems that need to attach structured, machine-readable context (issue links, telemetry keys, context tags) to errors for later triage
• Libraries and internal frameworks that define their own error leaf/wrapper types and need those types to still decode safely in older or newer versions of the consuming binary

Under The Hood

Architecture The library is organized as a facade package (errors, the module root) that re-exports functions from a set of focused internal packages: errbase (the core error type registry, encode/decode, and formatting machinery), errutil (the New/Wrap/As constructors), barriers (opacity/Handled() semantics), withstack (stack-trace capture), safedetails, hintdetail, hintdetail, issuelink, secondary, telemetrykeys, domains, contexttags, and markers (identity comparison). The errorspb package holds protobuf-generated types (errors.proto, hintdetail.proto, markers.proto, tags.proto) that back the network-portable encoding in errbase/encode.go and errbase/decode.go. This separation means the root package’s public surface (errutil_api.go, errbase_api.go, barriers_api.go, etc.) is almost entirely one-line delegations to the subpackages, keeping the facade stable while the encode/decode registry (keyed by TypeKey) is what actually changes behavior as new error types are registered. extgrpc and exthttp wire the same encode/decode path into gRPC status details and HTTP responses respectively.

Tech Stack Written in Go (module targets Go 1.25+), with error serialization built on github.com/gogo/protobuf and google.golang.org/protobuf, gRPC interop via google.golang.org/grpc and github.com/gogo/status/github.com/gogo/googleapis, and optional Sentry reporting through github.com/getsentry/sentry-go. It depends on sibling CockroachDB packages github.com/cockroachdb/redact (for PII redaction) and github.com/cockroachdb/logtags (for context-tag propagation), and on github.com/pkg/errors purely for interop/compatibility testing. Tests use github.com/stretchr/testify and github.com/cockroachdb/datadriven for table-driven data-driven test fixtures. CI (.github/workflows/ci.yaml) builds and tests against two Go versions and runs go mod tidy as a drift check.

Code Quality The repository has 41 _test.go files spread across nearly every subpackage (errbase, barriers, domains, markers, grpc, hintdetail, contexttags, exthttp, oserror, join, and the root package itself), including dedicated tests for stack-trace formatting, unknown-type decoding fallback, and string-ownership edge cases — areas that are easy to regress silently in an encode/decode-heavy library. Errors are handled explicitly throughout rather than swallowed, and the public API is extensively documented with doc comments explaining PII/safety implications for every constructor. There’s no separate lint config beyond go vet/go build in CI, and no CONTRIBUTING file, but the data-driven test fixtures and per-package test files suggest a deliberate, disciplined testing culture rather than an afterthought.

What Makes It Unique The standout capability is network-portable error identity: errors.Is() continues to work correctly even after an error has been encoded, sent over gRPC to a different node (potentially running an older or newer version of the software), and decoded there — something neither stdlib errors nor pkg/errors attempt. Combined with the automatic separation of safe/unsafe error content for Sentry reporting, this makes the library specifically suited to large distributed systems (it originates from CockroachDB itself) rather than being a generic error-wrapping convenience library.