error-handling-philosophy

Error Handling Philosophy

Go's error handling is a deliberate design choice, not an accident of a missing exception mechanism. "Errors are values" (Rob Pike, 2015, go.dev/blog/errors-are-values) means an error is a normal return value you inspect, transform, and pass along using ordinary code — not a control-flow event that unwinds the stack past code that didn't ask to handle it.

The core distinction: error values vs. exceptions

Exception-based languages let a throw skip past every intermediate frame until a catch matches — the calling code between throw and catch doesn't need to mention the possibility of failure at all. This is convenient but means you can't tell from a function signature whether it can fail, or what could go wrong, without reading its full implementation (and its callees', transitively).

Go's explicit (result, error) return makes failure a first-class, visible part of every function signature. The tradeoff: more boilerplate (if err != nil { return err } at every call site) in exchange for a caller that can never accidentally ignore an error path — the compiler won't stop you from ignoring it, but the pattern makes ignoring it a visibly deliberate act (an unused _ or a dropped return value) rather than an invisible omission.

When to return an error vs. when to panic

• Return an error for anything an external actor can cause: bad input, a network failure, a missing file, a database constraint violation, a downstream API returning 4xx/5xx. These are expected, recoverable conditions the caller should decide how to handle (retry, surface to a user, log and continue).
• Panic only for programmer errors that indicate the program's invariants are already broken and continuing would produce worse, silent corruption: an index genuinely out of bounds due to a logic bug, a nil pointer dereference from a broken invariant, a must-prefixed helper whose precondition was violated by calling code (e.g., regexp.MustCompile on a pattern that's a compile-time constant, so a failure can only mean a bug in this code, never bad input).
• Never panic on user input, network responses, or file contents — those are exactly the "external actor" cases errors exist for. A JSON parse failure on a request body is an error, not a panic.
• recover() is a last-resort safety net at a boundary (e.g., an HTTP server's top-level handler wrapper, so one panicking request doesn't take down the whole process) — not a substitute for proper error returns in the code beneath that boundary.