Go Error Handling
Available Scripts
scripts/check-errors.sh — Detects error handling anti-patterns: string comparison on err.Error(), bare return err without context, and log-and-return violations. Run bash scripts/check-errors.sh --help for options.
In Go, errors are values — they are
created by code and consumed by code.
Choosing an Error Strategy
- System boundary (RPC, IPC, storage)? → Wrap with
%v to avoid leaking internals
- Caller needs to match specific conditions? → Sentinel or typed error, wrap with
%w
- Caller just needs debugging context? →
fmt.Errorf("...: %w", err)
- 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:
func Bad() *os.PathError { }
func Good() error { }
Error Strings
Error strings should not be capitalized and should not end with
punctuation. Exception: exported names, proper nouns, or acronyms.
err := fmt.Errorf("Something bad happened.")
err := fmt.Errorf("something bad happened")
For displayed messages (logs, test failures, API responses), capitalization is
appropriate.
Return Values on Error
When a function returns an error, callers must treat all non-error return values
as unspecified unless explicitly documented.
Tip: Functions taking a context.Context should usually return an error
so callers can determine if the context was cancelled.
Handling Errors
When encountering an error, make a deliberate choice — do not discard
with _:
- Handle immediately — address the error and continue
- Return to caller — optionally wrapped with context
- In exceptional cases —
log.Fatal or panic
To intentionally ignore: add a comment explaining why.
n, _ := b.Write(p)
For related concurrent operations, use
errgroup:
g, ctx := errgroup.WithContext(ctx)
g.Go(func() error { return task1(ctx) })
g.Go(func() error { return task2(ctx) })
if err := g.Wait(); err != nil { return err }
Avoid In-Band Errors
Don't return -1, nil, or empty string to signal errors. Use multiple
returns:
func Lookup(key string) int
func Lookup(key string) (string, bool)
This prevents callers from writing Parse(Lookup(key)) — it causes a
compile-time error since Lookup(key) has 2 outputs.
Error Flow
Handle errors before normal code. Early returns keep the happy path unindented:
if err != nil {
return err
}
Handle errors once — either log or return, never both:
Error encountered?
├─ Caller can act on it? → Return (with context via %w)
├─ Top of call chain? → Log and handle
└─ Neither? → Log at appropriate level, continue
Read references/ERROR-FLOW.md when structuring complex error flows, deciding between logging vs returning, implementing the handle-once pattern, or choosing structured logging levels.
Error Types
Advisory: Recommended best practice.
| Caller needs to match? |
Message type |
Use |
| No |
static |
errors.New("message") |
| No |
dynamic |
fmt.Errorf("msg: %v", val) |
| Yes |
static |
var ErrFoo = errors.New("...") |
| Yes |
dynamic |
custom error type |
Default: Wrap with fmt.Errorf("...: %w", err). Escalate to sentinels for
errors.Is(), to custom types for errors.As().
Read references/ERROR-TYPES.md when defining sentinel errors, creating custom error types, or choosing error strategies for a package API.
Error Wrapping
Advisory: Recommended best practice.
- Use
%v: At system boundaries, for logging, to hide internal details
- Use
%w: To preserve error chain for errors.Is/errors.As
Key rules: Place %w at the end. Add context callers don't have. If
annotation adds nothing, return err directly.
Read references/WRAPPING.md when deciding between %v and %w, wrapping errors across package boundaries, or adding contextual information.
Validation: After implementing error handling, run bash scripts/check-errors.sh to detect common anti-patterns. Then run go vet ./... to catch additional issues.
Related Skills
- Error naming: See go-naming when naming sentinel errors (
ErrFoo) or custom error types
- Testing errors: See go-testing when testing error semantics with
errors.Is/errors.As or writing error-checking helpers
- Panic handling: See go-defensive when deciding between panic and error returns, or writing recover guards
- Guard clauses: See go-control-flow when structuring early-return error flow or reducing nesting
- Logging decisions: See go-logging when choosing log levels, configuring structured logging, or deciding what context to include in log messages
