go-error-handling

Use fmt.Errorf with the %w verb, for example fmt.Errorf("fetching user: %w", err), to preserve the error chain. Use %v only at public API boundaries where you want to hide internal error types from callers.

errors.Is matches an error against a sentinel value anywhere in the wrapped chain, while errors.As extracts a specific typed error from the chain into a target variable. Both traverse wrapped errors, unlike direct comparison or type assertion.

Do exactly one: either log the error or return it with added context, never both. Logging and returning creates duplicate entries in log aggregators and makes debugging harder.

Use samber/oops for production errors needing stack traces, user or tenant context, error codes, or structured attributes. It is a drop-in replacement compatible with errors.Is and errors.As.

Interpolating IDs or paths into error strings creates high-cardinality messages, so each unique value forms a separate group in Datadog, Loki, or Sentry. Attach variable data as structured attributes via slog or oops .With() instead.

Panic is acceptable only for truly unrecoverable states such as programmer errors or invalid initialization, like MustCompileRegex. Never panic for expected failures like network timeouts, and recover at goroutine or HTTP handler boundaries.