Go Error Handling

Go Error Handling

Expert guidance for proper error handling in Go.

Quick Reference

What Do You Need?

1. Error wrapping - Adding context to errors
2. Custom error types - Creating structured errors
3. Error inspection - errors.Is, errors.As
4. Sentinel errors - Package-level error values
5. Error conventions - When to wrap, return, or create

Specify a number or describe your error handling scenario.

Routing

Critical Rules

• Never ignore errors: Always check err != nil
• Wrap with %w: Use %w to preserve error type for errors.Is
• Wrap at boundaries: Wrap when crossing package boundaries
• Don't wrap twice: Avoid double-wrapping the same error
• Use errors.Is for sentinel: Check if error is a specific value
• Use errors.As for types: Extract and inspect custom error types

Error Handling Patterns

Wrapping Errors

// Good: Wrap with context using %w
func (s *Service) Process(id string) error {
    item, err := s.repo.Find(id)
    if err != nil {
        return fmt.Errorf("finding item %s: %w", id, err)
    }
    // ...
}

// Bad: Wrapping with %v loses error type
return fmt.Errorf("finding item %s: %v", id, err)  // Can't use errors.Is()

// Bad: Double wrapping
return fmt.Errorf("processing: %w", fmt.Errorf("finding: %w", err))

Custom Error Types

// Define custom error type
type ValidationError struct {
    Field   string
    Message string
}

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

// Return custom error
func (s *Service) Validate(input Input) error {
    if input.Email == "" {
        return &ValidationError{
            Field:   "email",
            Message: "is required",
        }
    }
    return nil
}

Error Inspection

// Check for sentinel error
if errors.Is(err, ErrNotFound) {
    // Handle not found
}

// Extract and check custom error type
var validationErr *ValidationError
if errors.As(err, &validationErr) {
    // Access validationErr.Field, validationErr.Message
}

// Check multiple possibilities
if errors.Is(err, ErrNotFound) || errors.Is(err, ErrAccessDenied) {
    // Handle both cases
}

Sentinel Errors

// Package-level sentinel errors
var (
    ErrNotFound    = errors.New("not found")
    ErrAccessDenied = errors.New("access denied")
    ErrInvalidInput = errors.New("invalid input")
)

// Use in returns
func (r *Repository) Find(id string) (*Item, error) {
    // ...
    return nil, ErrNotFound
}

// Check in callers
if err != nil {
    if errors.Is(err, ErrNotFound) {
        return nil, nil  // Not found is not an error here
    }
    return nil, err  // Other errors are still errors
}

When to Wrap vs Return

Common Mistakes

Reference Index

Success Criteria

Error handling is correct when:

• No errors are ignored (all checked)
• Errors wrapped at package boundaries with %w
• Custom error types for domain-specific errors
• Sentinel errors for expected conditions
• errors.Is used for sentinel checking
• errors.As used for type inspection
• No panic on errors (except in package init/main)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.