Mastering Error Handling in Go

Error handling is one of the most distinctive aspects of Go. Unlike languages that use exceptions, Go treats errors as values — plain return values that you explicitly check and handle. This design philosophy leads to more robust and predictable code once you understand how to work with it. As Darth Vader would say: *"I find your lack of error handling disturbing."* In Go, there is no escaping this responsibility — errors are first-class citizens, and the language makes sure you know it. In this guide, we will cover everything you need to master error handling in Go. ## The Basics: Errors as Values Like Neo in *The Matrix* discovering there is no spoon, Go programmers must accept a fundamental truth: *there are no exceptions — there are only errors.* Once you embrace this, everything clicks. In Go, the built-in `error` interface is defined as: ```go type error interface { Error() string } ``` Functions that can fail conventionally return an `error` as the last return value: ```go func divide(a, b float64) (float64, error) { if b == 0 { return 0, errors.New("division by zero") } return a / b, nil } func main() { result, err := divide(10, 0) if err != nil { fmt.Println("Error:", err) return } fmt.Println("Result:", result) } ``` The `nil` check is the idiomatic Go way of checking whether an operation succeeded. ## Creating Custom Errors While `errors.New` and `fmt.Errorf` are convenient, you often need richer error types to convey more context. ### Struct-based Custom Errors ```go type ValidationError struct { Field string Message string } func (e *ValidationError) Error() string { return fmt.Sprintf("validation error on field %q: %s", e.Field, e.Message) } func validateAge(age int) error { if age < 0 { return &ValidationError{Field: "age", Message: "must be non-negative"} } if age > 150 { return &ValidationError{Field: "age", Message: "unrealistically large value"} } return nil } ``` Custom error types let callers inspect the error and make decisions based on its fields. ## Sentinel Errors Think of sentinel errors as Obi-Wan Kenobi calmly waving his hand: *"These aren't the errors you're looking for."* They are named, predeclared values that let callers identify exactly what went wrong — no guesswork, no string parsing, just a clean identity check. Sentinel errors are predeclared error values used to signal specific conditions. The standard library uses them extensively: ```go var ( ErrNotFound = errors.New("not found") ErrPermission = errors.New("permission denied") ErrTimeout = errors.New("operation timed out") ) func findUser(id int) (*User, error) { user, ok := db[id] if !ok { return nil, ErrNotFound } return user, nil } // Callers can compare directly: if errors.Is(err, ErrNotFound) { // handle not found case } ``` Sentinel errors are best for stable, well-known error conditions that callers need to branch on. ## Error Wrapping with `fmt.Errorf` and `%w` Go 1.13 introduced error wrapping, which lets you add context to an error while preserving the original: ```go func readConfig(path string) (*Config, error) { data, err := os.ReadFile(path) if err != nil { return nil, fmt.Errorf("readConfig: %w", err) } // ... return config, nil } ``` The `%w` verb wraps the error, making it inspectable by `errors.Is` and `errors.As`. ## Unwrapping Errors: `errors.Is` and `errors.As` ### `errors.Is` — Checking for a Specific Error `errors.Is` traverses the entire error chain looking for a matching value: ```go err := readConfig("missing.yaml") if errors.Is(err, os.ErrNotExist) { fmt.Println("Config file does not exist") } ``` This works even when the error has been wrapped multiple layers deep. ### `errors.As` — Extracting a Specific Error Type `errors.As` traverses the chain looking for an error that can be assigned to the target type: ```go func processInput(input string) error { return fmt.Errorf("processInput: %w", &ValidationError{ Field: "input", Message: "cannot be empty", }) } func main() { err := processInput("") var ve *ValidationError if errors.As(err, &ve) { fmt.Printf("Validation failed on field: %s\n", ve.Field) } } ``` ## Implementing the `Unwrap` Method For custom error types that wrap another error, implement the `Unwrap` method so that `errors.Is` and `errors.As` can traverse the chain: ```go type QueryError struct { Query string Err error } func (e *QueryError) Error() string { return fmt.Sprintf("query %q failed: %v", e.Query, e.Err) } func (e *QueryError) Unwrap() error { return e.Err } ``` ## Panic and Recover If you have ever read *The Hitchhiker's Guide to the Galaxy*, you know the most important advice printed on its cover in large, friendly letters: **DON'T PANIC**. Go shares this philosophy entirely. While errors are the preferred mechanism for expected failure cases, Go provides `panic` and `recover` for truly exceptional situations. ```go func safeDiv(a, b int) (result int, err error) { defer func() { if r := recover(); r != nil { err = fmt.Errorf("recovered from panic: %v", r) } }() result = a / b return } ``` Use `panic` sparingly — typically only for programmer errors (e.g., invalid arguments to a function) or truly unrecoverable situations. Always recover at package boundaries. ## Best Practices ### 1. Always Handle Errors Remember the Black Knight from *Monty Python and the Holy Grail*? He kept insisting *"It's just a flesh wound!"* while losing every limb. Silently discarding errors with `_` is the software equivalent — small ignored wounds that quietly become fatal bugs. Never silently ignore errors. If you genuinely don't need to handle an error, document why with a comment. ```go // Bad f, _ := os.Open("file.txt") // Good f, err := os.Open("file.txt") if err != nil { return fmt.Errorf("open file: %w", err) } ``` ### 2. Add Context When Wrapping When wrapping errors, add context that describes *what* was being done — not just *what* failed. ```go // Less helpful return fmt.Errorf("%w", err) // More helpful return fmt.Errorf("fetchUserProfile(id=%d): %w", id, err) ``` ### 3. Prefer `errors.Is` / `errors.As` Over Direct Comparison Direct `==` comparison breaks when errors are wrapped. Use the standard library helpers instead. ```go // Fragile — fails if err is wrapped if err == ErrNotFound { ... } // Robust if errors.Is(err, ErrNotFound) { ... } ``` ### 4. Return Errors, Don't Log and Return In *Ghostbusters*, when something goes wrong, you call the Ghostbusters — you don't also fire the alarm, call the mayor, *and* call the Ghostbusters. Pick one. The same rule applies here: either log the error or return it, not both. Avoid logging an error and then returning it — this leads to duplicate log entries. Either log it at the top level or return it for the caller to handle. ```go // Bad: logs AND returns log.Printf("error: %v", err) return err // Good: just return and let the caller decide return fmt.Errorf("doSomething: %w", err) ``` ### 5. Keep Error Messages Lowercase By convention, Go error strings should be lowercase and not end with punctuation, since they are often composed into larger messages. ```go // Bad errors.New("File not found.") // Good errors.New("file not found") ``` ## Putting It All Together Here is a practical example combining everything we covered: ```go package main import ( "errors" "fmt" "strconv" ) var ErrNegativeNumber = errors.New("negative number") type ParseError struct { Input string Err error } func (e *ParseError) Error() string { return fmt.Sprintf("parse error for input %q: %v", e.Input, e.Err) } func (e *ParseError) Unwrap() error { return e.Err } func parsePositive(s string) (int, error) { n, err := strconv.Atoi(s) if err != nil { return 0, &ParseError{Input: s, Err: err} } if n < 0 { return 0, &ParseError{Input: s, Err: ErrNegativeNumber} } return n, nil } func main() { inputs := []string{"42", "-5", "abc"} for _, input := range inputs { val, err := parsePositive(input) if err != nil { var pe *ParseError if errors.As(err, &pe) { fmt.Printf("Bad input: %s\n", pe.Input) } if errors.Is(err, ErrNegativeNumber) { fmt.Println("Hint: provide a positive number") } continue } fmt.Printf("Parsed: %d\n", val) } } ``` ## Conclusion Go error handling requires a bit of a mindset shift if you are coming from exception-based languages, but the explicitness it enforces pays dividends in code clarity and reliability. By treating errors as values, wrapping them with context, and using `errors.Is` / `errors.As` for inspection, you can write Go programs that fail gracefully and are easy to debug. As Samwise Gamgee wisely put it: *"It's a dangerous business, going out your door... but I suppose the answer is to keep going."* The same goes for error handling — keep wrapping, keep checking, and your code will be as resilient as the Fellowship of the Ring. Happy coding!