Structured error handling in Golang with samber/oops — error builders, stack traces, error codes, error context, error wrapping, error attributes, user-facing vs developer messages, panic recovery, and logger integration. Apply when using or adopting samber/oops, or when the codebase already imports

Persona: You are a Go engineer who treats errors as structured data. Every error carries enough context — domain, attributes, trace — for an on call engineer to diagnose the problem without asking the developer. samber/oops Structured Error Handling samber/oops is a drop in replacement for Go's standard error handling that adds structured context, stack traces, error codes, public messages, and panic recovery. Variable data goes in .With() attributes (not the message string), so APM tools (Datadog, Loki, Sentry) can group errors properly. Unlike the stdlib approach (adding slog attributes at the log site), oops attributes travel with the error through the call stack. Why use samber/oops Standard Go errors lack context — you see connection failed but not which user triggered it, what query was running, or the full call stack. samber/oops provides: Structured context — key value attributes on any error Stack traces — automatic call stack capture Error codes — machine readable identifiers Public messages — user safe messages separate from technical details Low cardinality messages — variable data in .With() attributes, not the message string, so APM tools group errors properly This skill is not exhaustive — refer to library documentation and code examples for more information: For Go package docs, symbols, versions, importers, and known vulnerabilities, → See samber/cc skills golang@golang pkg go dev skill ( godig ), preferred over Context7 for Go package facts. To navigate this library's usage in your own code (definitions, call sites, diagnostics), → See samber/cc skills golang@golang gopls skill ( gopls ). Context7 remains a fallback for docs not indexed on pkg.go.dev. Core pattern: Error builder chain All oops errors use a fluent builder pattern: Terminal methods: .Errorf(format, args...) — create a new error .Wrap(err) — wrap an existing error .Wrapf(err, format, args...) — wrap with a message .Join(err1, err2, ...) — combine multiple errors .Recover(fn) / .Recoverf(fn, format, args...) — convert panic to error Error builder methods Methods Use case .With("key", value) Add custom key value attribute (lazy func() any values supported) .WithContext(ctx, "key1", "key2") Extract values from Go context into attributes (lazy values supported) .In("domain") Set the feature/service/domain .Tags("auth", "sql") Add categorization tags (query with err.HasTag("tag") ) .Code("iam authz missing permission") Set machine readable error identifier/slug .Public("Could not fetch user.") Set user safe message (separate from technical details) .Hint("Runbook: https://doc.acme.org/doc/abcd.md") Add debugging hint for developers .Owner("team/slack") Identify responsible team/owner .User(id, "k", "v") Add user identifier and attributes .Tenant(id, "k", "v") Add tenant/organization context and attributes .Trace(id) Add trace / correlation ID (default: ULID) .Span(id) Add span ID representing a unit of work/operation (default: ULID) .Time(t) Override error timestamp (default: time.Now() ) .Since(t) Set duration based on time since t (exposed via err.Duration() ) .Duration(d) Set explicit error duration .Request(req, includeBody) Attach http.Request (optionally including body) .Response(res, includeBody) Attach http.Response (optionally including body) oops.FromContext(ctx) Start from an OopsErrorBuilder stored in a Go context Common scenarios Database/repository layer HTTP handler layer Service layer with reusable builder Error wrapping best practices DO: Wrap directly, no nil check needed DO: Add context at each layer Each architectural layer SHOULD add context via Wrap/Wrapf — at least once per package boundary (not necessarily at every function call). DO: Keep error messages low cardinality Error messages MUST be low cardinality for APM aggregation. Interpolating variable data into the message breaks grouping in Datadog, Loki, Sentry. Panic recovery oops.Recover() MUST be used in goroutine boundaries. Convert panics to structured errors: Accessing error information samber/oops errors implement the standard error interface. Access additional info: Output formats Context propagation Carry error context through Go contexts: For assertions, configuration, and additional logger examples, see [Advanced patterns](./references/advanced.md). References [github.com/samber/oops](https://github.com/samber/oops) [pkg.go.dev/github.com/samber/oops](https://pkg.go.dev/github.com/samber/oops) Cross References → See samber/cc skills golang@golang error handling skill for general error handling patterns → See samber/cc skills golang@golang observability skill for logger integration and structured logging

golang-samber-oops