go-error-handling

Go Error Handling

Errors in Go are values. Treat them as part of the API: choose a strategy per failure mode, propagate with wrapping, inspect with errors.Is/As, and handle each error exactly once.

Core Rules

1. Errors are values, not exceptions. Return them; do not panic across API boundaries.
2. Handle each error exactly once. Either log it or return it — never both.
3. The caller decides what is exceptional. Library code returns; binaries (or top-level handlers) decide whether to log, retry, or exit.
4. Wrap only when you add real context. A wrap that just repeats the function name is noise. Use %w to preserve identity; %v to deliberately hide an unstable type.

Strategy Decision

Pick the simplest strategy that meets the caller's needs:

Strategy	When to use	Example
Opaque error (default)	Caller only needs to know something failed	errors.New("invalid input")
Sentinel error	Caller needs to test for a specific named condition	io.EOF, sql.ErrNoRows
Typed error	Caller needs structured fields (path, code, retry-after)	*os.PathError, *url.Error
Joined errors	A single operation produced several independent failures	errors.Join(errA, errB)

Read references/strategy-decision.md when the caller's needs are unclear or when migrating between strategies without breaking callers.

Writing Errors

Strings

• Lowercase, no trailing punctuation. Errors are composed: fmt.Errorf("write %s: %w", path, err) reads as one sentence.
• Be specific. "open config: permission denied" beats "failed to open file".
• Do not include the function name. Stack context is added by wrapping at each layer.

Creating

// Opaque — the caller only checks != nil
return errors.New("invalid character in token")

// Sentinel — exported, package-level, named ErrXxx
var ErrNotFound = errors.New("user: not found")

// Typed — when callers need structured fields
type ValidationError struct {
    Field string
    Rule  string
}
func (e *ValidationError) Error() string {
    return fmt.Sprintf("validation: %s violates %s", e.Field, e.Rule)
}