Error Handling in Go

The 3 AM Alert That Taught Me Everything

It was 3:17 AM when PagerDuty woke me up. Our payment processing service was down. The logs showed:

panic: runtime error: invalid memory address or nil pointer dereference

The code that caused it:

func processPayment(orderID string) error {
    order := getOrder(orderID)  // Returned nil on not found
    // Crashed here - didn't check for nil!
    amount := order.Total
    charge(order.CustomerID, amount)
    return nil
}

I had ignored the error from getOrder. In Python, this would have raised an exception I could catch. In Go, I just got a panic and 2 hours of downtime.

The fix was embarrassingly simple:

func processPayment(orderID string) error {
    order, err := getOrder(orderID)
    if err != nil {
        return fmt.Errorf("failed to get order %s: %w", orderID, err)
    }
    
    if err := charge(order.CustomerID, order.Total); err != nil {
        return fmt.Errorf("failed to charge customer: %w", err)
    }
    
    return nil
}

That 3 AM incident taught me: explicit error handling isn't verbose - it's essential. This article covers everything I learned about Go's error philosophy.

---

The Error Interface

Go's error handling is built on a simple interface:

type error interface {
    Error() string
}

Any type with an Error() method satisfies this interface.

Creating Errors

import "errors"

// Simple error
err := errors.New("something went wrong")

// Formatted error
err := fmt.Errorf("failed to process user %s: %s", userID, reason)

Checking Errors

result, err := doSomething()
if err != nil {
    // Handle error
    log.Println("Error:", err)
    return err
}
// Use result
fmt.Println(result)

This pattern appears everywhere in Go code:

file, err := os.Open("config.json")
if err != nil {
    return err
}
defer file.Close()

data, err := io.ReadAll(file)
if err != nil {
    return err
}

var config Config
err = json.Unmarshal(data, &config)
if err != nil {
    return err
}

---

Error Handling Patterns

Early Return

Most idiomatic - exit early on errors:

func processUser(id string) error {
    user, err := getUser(id)
    if err != nil {
        return err
    }
    
    if err := validateUser(user); err != nil {
        return err
    }
    
    if err := saveUser(user); err != nil {
        return err
    }
    
    return nil
}

Handle and Continue

func processUsers(ids []string) []error {
    var errors []error
    
    for _, id := range ids {
        if err := processUser(id); err != nil {
            errors = append(errors, err)
            continue  // Try next user
        }
    }
    
    return errors
}

Wrap and Return

Add context to errors:

func loadConfig(filename string) (*Config, error) {
    data, err := os.ReadFile(filename)
    if err != nil {
        return nil, fmt.Errorf("read config file: %w", err)
    }
    
    var config Config
    err = json.Unmarshal(data, &config)
    if err != nil {
        return nil, fmt.Errorf("parse config JSON: %w", err)
    }
    
    return &config, nil
}

The %w verb wraps the error, preserving the original.

---

Error Wrapping (Go 1.13+)

Why Wrap Errors?

// Without wrapping - lose original error
err := doSomething()
if err != nil {
    return fmt.Errorf("operation failed")
    // Original error information lost!
}

// With wrapping - preserve error chain
err := doSomething()
if err != nil {
    return fmt.Errorf("operation failed: %w", err)
    // Original error preserved
}

Unwrapping Errors

import "errors"

// Check specific error
var ErrNotFound = errors.New("not found")

func getUser(id string) (*User, error) {
    // ...
    if userNotInDB {
        return nil, ErrNotFound
    }
    return user, nil
}

// Check with errors.Is
user, err := getUser("123")
if errors.Is(err, ErrNotFound) {
    // Handle not found specifically
    return createDefaultUser()
}
if err != nil {
    // Handle other errors
    return err
}

Real example from my API:

var (
    ErrUnauthorized = errors.New("unauthorized")
    ErrNotFound     = errors.New("not found")
    ErrBadRequest   = errors.New("bad request")
)

func handleError(w http.ResponseWriter, err error) {
    switch {
    case errors.Is(err, ErrUnauthorized):
        http.Error(w, err.Error(), http.StatusUnauthorized)
    case errors.Is(err, ErrNotFound):
        http.Error(w, err.Error(), http.StatusNotFound)
    case errors.Is(err, ErrBadRequest):
        http.Error(w, err.Error(), http.StatusBadRequest)
    default:
        http.Error(w, "Internal server error", http.StatusInternalServerError)
    }
}

---

Custom Error Types

Struct Errors

type ValidationError struct {
    Field   string
    Message string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("validation error on field %s: %s", e.Field, e.Message)
}

func validateEmail(email string) error {
    if !strings.Contains(email, "@") {
        return &ValidationError{
            Field:   "email",
            Message: "must contain @ symbol",
        }
    }
    return nil
}

// Check type with errors.As
err := validateEmail("invalid")
var valErr *ValidationError
if errors.As(err, &valErr) {
    fmt.Printf("Field: %s, Message: %s\n", valErr.Field, valErr.Message)
}

Real Example: HTTP Errors

From my REST API:

type APIError struct {
    StatusCode int
    Message    string
    Err        error
}

func (e *APIError) Error() string {
    if e.Err != nil {
        return fmt.Sprintf("%s: %v", e.Message, e.Err)
    }
    return e.Message
}

func (e *APIError) Unwrap() error {
    return e.Err
}

// Factory functions
func NewBadRequestError(message string, err error) *APIError {
    return &APIError{
        StatusCode: http.StatusBadRequest,
        Message:    message,
        Err:        err,
    }
}

func NewNotFoundError(message string) *APIError {
    return &APIError{
        StatusCode: http.StatusNotFound,
        Message:    message,
    }
}

// Usage in handler
func getUser(w http.ResponseWriter, r *http.Request) {
    id := r.URL.Query().Get("id")
    if id == "" {
        err := NewBadRequestError("id parameter required", nil)
        handleAPIError(w, err)
        return
    }
    
    user, err := db.GetUser(id)
    if err != nil {
        err := NewNotFoundError("user not found")
        handleAPIError(w, err)
        return
    }
    
    json.NewEncoder(w).Encode(user)
}

func handleAPIError(w http.ResponseWriter, err error) {
    var apiErr *APIError
    if errors.As(err, &apiErr) {
        http.Error(w, apiErr.Message, apiErr.StatusCode)
        return
    }
    http.Error(w, "Internal server error", http.StatusInternalServerError)
}

---

Sentinel Errors

Pre-defined errors for comparison:

package os

var (
    ErrInvalid    = errors.New("invalid argument")
    ErrPermission = errors.New("permission denied")
    ErrExist      = errors.New("file already exists")
    ErrNotExist   = errors.New("file does not exist")
)

Usage:

file, err := os.Open("config.json")
if errors.Is(err, os.ErrNotExist) {
    // Create default config
    return createDefaultConfig()
}
if err != nil {
    return err
}

My convention for sentinel errors:

package user

var (
    ErrUserNotFound      = errors.New("user not found")
    ErrEmailExists       = errors.New("email already registered")
    ErrInvalidPassword   = errors.New("invalid password")
    ErrAccountSuspended  = errors.New("account suspended")
)

func Login(email, password string) (*User, error) {
    user, err := db.FindByEmail(email)
    if err != nil {
        return nil, ErrUserNotFound
    }
    
    if user.Suspended {
        return nil, ErrAccountSuspended
    }
    
    if !checkPassword(user, password) {
        return nil, ErrInvalidPassword
    }
    
    return user, nil
}

---

Panic and Recover

When to Panic

Rule: Almost never! Panics are for programming errors, not expected errors.

// Good: Return error
func divide(a, b float64) (float64, error) {
    if b == 0 {
        return 0, errors.New("division by zero")
    }
    return a / b, nil
}

// Bad: Panic for expected error
func divide(a, b float64) float64 {
    if b == 0 {
        panic("division by zero")  // Don't do this!
    }
    return a / b
}

Acceptable panic use cases:

1. Initialization errors (can't continue)

2. Programmer errors (index out of bounds)

3. Unrecoverable situations

func init() {
    config, err := loadConfig()
    if err != nil {
        panic("failed to load config: " + err.Error())
        // Can't run without config
    }
}

Recover from Panic

func recoverFromPanic() {
    defer func() {
        if r := recover(); r != nil {
            fmt.Println("Recovered from panic:", r)
            // Log error, clean up, etc.
        }
    }()
    
    // Code that might panic
    riskyOperation()
}

Real example - HTTP server shouldn't crash on handler panic:

func safeHandler(h http.HandlerFunc) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if err := recover(); err != nil {
                log.Printf("Panic in handler: %v\n%s", err, debug.Stack())
                http.Error(w, "Internal server error", 500)
            }
        }()
        
        h(w, r)
    }
}

// Usage
http.HandleFunc("/api/users", safeHandler(handleUsers))

---

Practical Error Handling Example

My file processing pipeline:

type ProcessingError struct {
    Filename string
    Line     int
    Err      error
}

func (e *ProcessingError) Error() string {
    return fmt.Sprintf("error processing %s at line %d: %v", 
        e.Filename, e.Line, e.Err)
}

func (e *ProcessingError) Unwrap() error {
    return e.Err
}

func processFile(filename string) error {
    file, err := os.Open(filename)
    if err != nil {
        return fmt.Errorf("open file: %w", err)
    }
    defer file.Close()
    
    scanner := bufio.NewScanner(file)
    lineNum := 0
    
    for scanner.Scan() {
        lineNum++
        line := scanner.Text()
        
        if err := processLine(line); err != nil {
            return &ProcessingError{
                Filename: filename,
                Line:     lineNum,
                Err:      err,
            }
        }
    }
    
    if err := scanner.Err(); err != nil {
        return fmt.Errorf("scanner error: %w", err)
    }
    
    return nil
}

func processBatch(filenames []string) []error {
    var errors []error
    
    for _, filename := range filenames {
        if err := processFile(filename); err != nil {
            log.Printf("Error processing %s: %v\n", filename, err)
            errors = append(errors, err)
            // Continue with other files
        }
    }
    
    return errors
}

// Usage
files := []string{"data1.csv", "data2.csv", "data3.csv"}
errors := processBatch(files)

if len(errors) > 0 {
    log.Printf("Processed with %d errors\n", len(errors))
    for _, err := range errors {
        var procErr *ProcessingError
        if errors.As(err, &procErr) {
            log.Printf("  %s line %d: %v\n", 
                procErr.Filename, procErr.Line, procErr.Err)
        } else {
            log.Printf("  %v\n", err)
        }
    }
}

---

Error Handling Best Practices

1. Don't Ignore Errors

// Bad
data, _ := os.ReadFile("config.json")

// Good
data, err := os.ReadFile("config.json")
if err != nil {
    return fmt.Errorf("read config: %w", err)
}

2. Add Context When Wrapping

// Bad - no context
if err != nil {
    return err
}

// Good - add context
if err != nil {
    return fmt.Errorf("failed to process user %s: %w", userID, err)
}

3. Handle Errors at the Right Level

func getUserEmail(id string) (string, error) {
    user, err := getUser(id)
    if err != nil {
        return "", err  // Let caller handle
    }
    return user.Email, nil
}

func sendEmail(userID string) error {
    email, err := getUserEmail(userID)
    if err != nil {
        // Handle here - know what to do
        log.Printf("Failed to get email for user %s: %v", userID, err)
        return nil  // Don't fail entire operation
    }
    
    return sendEmailTo(email)
}

4. Use Custom Error Types for Complex Cases

type RetryableError struct {
    Err        error
    RetryAfter time.Duration
}

func (e *RetryableError) Error() string {
    return fmt.Sprintf("%v (retry after %v)", e.Err, e.RetryAfter)
}

func makeRequest(url string) error {
    resp, err := http.Get(url)
    if err != nil {
        return err
    }
    defer resp.Body.Close()
    
    if resp.StatusCode == 429 {
        retryAfter, _ := time.ParseDuration(resp.Header.Get("Retry-After"))
        return &RetryableError{
            Err:        errors.New("rate limited"),
            RetryAfter: retryAfter,
        }
    }
    
    return nil
}

5. Log and Return

// Bad - lose error info
if err != nil {
    log.Println(err)
    return nil
}

// Good - log and return
if err != nil {
    log.Printf("Failed to process: %v", err)
    return fmt.Errorf("process failed: %w", err)
}

---

Errors vs Exceptions

Coming from languages with exceptions, Go's approach felt strange:

Exceptions (Python/Java):

• Hidden control flow

• Catch multiple layers up

• Easy to forget

• Stack unwinding

Go Errors:

• Explicit in function signature

• Must check at each level

• Can't forget (compiler enforces)

• Clear error flow

The 3 AM incident proved Go's approach right: I can't ignore errors by accident.

---

Your Challenge

Build a configuration loader with proper error handling:

type Config struct {
    Host     string
    Port     int
    Database string
}

// Implement these with proper error handling:
// - LoadConfig(filename string) (*Config, error)
// - ValidateConfig(*Config) error
// - SaveConfig(filename string, cfg *Config) error

// Requirements:
// 1. Return wrapped errors with context
// 2. Use custom error types where appropriate
// 3. Handle file not found differently than invalid JSON
// 4. Validate port is 1-65535
// 5. Create helpful error messages

---

Key Takeaways

1. Errors are values - returned explicitly, not thrown

2. Check every error - compiler won't let you forget

3. Wrap errors with context - use %w verb

4. Use errors.Is and errors.As - check error types safely

5. Custom error types - for complex error handling

6. Panic rarely - only for programming errors

7. Recover in servers - don't crash on panics

---

What I Learned

The 3 AM payment incident transformed my view on error handling:

Before: Error checking feels verbose and repetitive After: Explicit errors prevent production disasters

In Python, I'd write:

try:
    order = get_order(order_id)
    charge(order.customer_id, order.total)
except Exception as e:
    log.error(f"Payment failed: {e}")

Simple! But which exceptions can be raised? Where do they come from? I didn't know until production.

In Go:

order, err := getOrder(orderID)
if err != nil {
    return fmt.Errorf("get order: %w", err)
}

if err := charge(order.CustomerID, order.Total); err != nil {
    return fmt.Errorf("charge customer: %w", err)
}

More lines? Yes. But every error path is visible. Every failure is handled. No surprises at 3 AM.

Go's error handling isn't verbose - it's honest.

---

Next: Concurrency - Goroutines and Channels

In the next article, we'll explore Go's killer feature: built-in concurrency with goroutines and channels. You'll learn how the word go transformed my approach to parallel processing.