go-error-handling

Go Error Handling

Compatibility: errors.Is, errors.As, and %w wrapping require Go 1.13+; structured logging examples may use log/slog from Go 1.21+.

Resource Routing

• scripts/check-errors.sh - Run when checking string-based error matching, bare error propagation, and log-and-return patterns.
• scripts/check-errors-ast.go - Implementation helper invoked by check-errors.sh; patch this when changing error-flow analysis behavior.
• references/ERROR-FLOW.md - Read when deciding where to handle, wrap, log, or return errors.
• references/ERROR-TYPES.md - Read when choosing sentinel errors, typed errors, or opaque errors.
• references/WRAPPING.md - Read when choosing %w versus %v or crossing package boundaries.

In Go, errors are values — they are created by code and consumed by code.

Choosing an Error Strategy

1. System boundary (RPC, IPC, storage)? → Wrap with %v to avoid leaking internals
2. Caller needs to match specific conditions? → Sentinel or typed error, wrap with %w
3. Caller just needs debugging context? → fmt.Errorf("...: %w", err)
4. Leaf function, no wrapping needed? → Return the error directly

Default: wrap with %w and place it at the end of the format string.

---

Core Rules

Never Return Concrete Error Types

Never return concrete error types from exported functions — a concrete nil pointer can become a non-nil interface:

// Bad: Concrete type can cause subtle bugs
func Bad() *os.PathError { /*...*/ }

// Good: Always return the error interface
func Good() error { /*...*/ }

Error Strings

Error strings should not be capitalized and should not end with punctuation. Exception: exported names, proper nouns, or acronyms.

// Bad
err := fmt.Errorf("Something bad happened.")

// Good
err := fmt.Errorf("something bad happened")

For displayed messages (logs, test failures, API responses), capitalization is appropriate.

Return Values on Error