go-error-handling

Go Error Handling

Go's explicit error handling is a feature, not a limitation. These patterns ensure errors are informative, actionable, and properly propagated.

1. Error Decision Tree

When creating or returning an error, follow this tree:

1. Simple, no extra context needed? → errors.New("message")
2. Need to add context to existing error? → fmt.Errorf("doing X: %w", err)
3. Caller needs to detect this error? → Sentinel var or custom type
4. Error carries structured data? → Custom type implementing error
5. Propagating from downstream? → Wrap with %w and add context

2. Sentinel Errors

Use package-level var for errors that callers need to check:

// ✅ Good — exported sentinel error
var (
    ErrNotFound     = errors.New("user: not found")
    ErrUnauthorized = errors.New("user: unauthorized")
)

// Naming convention: Err + Description
// Prefix with package context in the message

Callers check with errors.Is:

if errors.Is(err, user.ErrNotFound) {
    // handle not found
}

NEVER compare errors with ==. Always use errors.Is().

3. Custom Error Types

When errors need to carry structured information:

type ValidationError struct {
    Field   string
    Message string
}

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

// Callers extract with errors.As:
var valErr *ValidationError
if errors.As(err, &valErr) {
    log.Printf("invalid field: %s", valErr.Field)
}

4. Error Wrapping

ALWAYS add context when propagating errors up the stack. Use %w to preserve the error chain:

// ✅ Good — context added, chain preserved
func getUser(id int64) (*User, error) {
    row, err := db.QueryRow(ctx, query, id)
    if err != nil {
        return nil, fmt.Errorf("get user %d: %w", id, err)
    }
    // ...
}

// ❌ Bad — no context
return nil, err

// ❌ Bad — chain broken, callers can't errors.Is/As
return nil, fmt.Errorf("failed: %v", err)