golang-error-handling

Use fmt.Errorf with the %w verb to wrap errors while preserving the chain, for example fmt.Errorf("fetching user: %w", err). Use %v instead of %w at public API boundaries to prevent callers from unwrapping internal error types.

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. For Go 1.26+, errors.AsType[T] offers simpler generic syntax for type extraction.

Handle each error exactly once: either log it or return it, never both. Logging and returning causes duplicate entries at every layer, cluttering log aggregation tools. Return with context and let the top-level handler log it.

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, keeping variable data out of low-cardinality log messages.

Use errors.Join (Go 1.20+) to combine independent errors, such as validation failures across multiple fields or shutdown errors from multiple resources. The joined error remains inspectable with errors.Is and errors.As for each inner error.

Panic is only acceptable for truly unrecoverable states like programmer errors or invalid initialization, never for expected failures such as network timeouts. Recover from panics with deferred functions at goroutine boundaries like HTTP handlers.