Error Handling

Why Error Handling Matters

Go's explicit error handling prevents hidden control flow and forces developers to handle errors at each step. Understanding the error interface, error wrapping (Go 1.13+), errors.Is/As, and sentinel errors prevents error information loss and enables robust error handling in production systems.

Core benefits:

Explicit handling: Errors visible at call site (no hidden exceptions)
Error context: Wrapping preserves error chain with context
Type safety: errors.As enables type-specific error handling
Sentinel matching: errors.Is checks error identity through wrapping

Problem: Before Go 1.13, error wrapping lost original errors, preventing proper error identification. Manual string formatting destroyed error semantics.

Solution: Start with error interface and errors.New(), understand limitations (no wrapping), then use fmt.Errorf with %w and errors.Is/As for production error handling.

Standard Library: Error Interface

Go's error type is an interface with single method.

Pattern from standard library:

package main
 
import (
    "errors"
    // => Standard library for error creation
    // => errors.New creates error from string
    "fmt"
    // => Standard library for formatted output
)
 
// ERROR INTERFACE (from standard library):
// type error interface {
//     Error() string
// }
// => Any type with Error() string implements error
// => Simple interface enables flexible error types
 
func divide(a, b float64) (float64, error) {
    // => Returns result and error
    // => Second return value is error (convention)
    // => error is nil on success, non-nil on failure
 
    if b == 0 {
        // => Division by zero detected
 
        return 0, errors.New("division by zero")
        // => errors.New creates error from string
        // => Returns error interface
        // => Result is zero value (ignored on error)
    }
 
    return a / b, nil
    // => Success: return result and nil error
    // => nil indicates no error
}
 
func main() {
    result, err := divide(10, 2)
    // => err is nil (success case)
 
    if err != nil {
        // => Check error before using result
        // => Go convention: check error immediately
 
        fmt.Println("Error:", err)
        // => Won't execute (err is nil)
        return
    }
 
    fmt.Println("Result:", result)
    // => Output: Result: 5
    // => Only reached if err is nil
 
    // Error case
    result2, err2 := divide(10, 0)
    // => err2 is non-nil (error case)
 
    if err2 != nil {
        // => err2 is errors.errorString ("division by zero")
 
        fmt.Println("Error:", err2)
        // => Output: Error: division by zero
        // => err2.Error() called implicitly by fmt
 
        return
        // => Exit on error (result2 invalid)
    }
 
    fmt.Println("Result:", result2)
    // => Won't execute (returned above)
}

Custom error types:

package main
 
import "fmt"
 
// Custom error type
type ValidationError struct {
    Field   string
    // => Field that failed validation
    Message string
    // => Error message
}
 
func (e *ValidationError) Error() string {
    // => Implements error interface
    // => Required method for error type
 
    return fmt.Sprintf("validation error on %s: %s", e.Field, e.Message)
    // => Formats error message
    // => Output: validation error on email: invalid format
}
 
func validateEmail(email string) error {
    // => Returns error interface
    // => Actual type is *ValidationError
 
    if email == "" {
        // => Empty email detected
 
        return &ValidationError{
            Field:   "email",
            Message: "cannot be empty",
        }
        // => Returns custom error type
        // => Satisfies error interface (*ValidationError has Error method)
    }
 
    if !contains(email, "@") {
        // => Basic email validation
 
        return &ValidationError{
            Field:   "email",
            Message: "invalid format",
        }
    }
 
    return nil
    // => Validation passed
}
 
func contains(s, substr string) bool {
    // => Helper function (simplified)
    for i := 0; i <= len(s)-len(substr); i++ {
        if s[i:i+len(substr)] == substr {
            return true
        }
    }
    return false
}
 
func main() {
    err := validateEmail("invalid")
    // => err is *ValidationError (concrete type)
 
    if err != nil {
        fmt.Println(err)
        // => Output: validation error on email: invalid format
        // => Calls Error() method
    }
}

Limitations before Go 1.13:

No standard error wrapping (information lost)
Cannot check if error is specific type after wrapping
String concatenation destroys error semantics
No error chain inspection

Production Framework: Error Wrapping (Go 1.13+)

Go 1.13 introduced error wrapping with fmt.Errorf %w verb and errors.Is/As for error inspection.

Pattern: Error Wrapping with %w:

package main
 
import (
    "errors"
    // => Standard library errors package
    // => errors.Is/As for error inspection
    "fmt"
    // => fmt.Errorf with %w for wrapping
)
 
var ErrNotFound = errors.New("not found")
// => SENTINEL ERROR: predefined error
// => Exported (capitalized) for external use
// => Used for error identity checking
 
func fetchUser(id string) error {
    // => Simulates database fetch
    // => Returns wrapped error on failure
 
    // Simulate database error
    if id == "invalid" {
        // => User not found case
 
        return fmt.Errorf("failed to fetch user %s: %w", id, ErrNotFound)
        // => %w wraps ErrNotFound (preserves error chain)
        // => Adds context ("failed to fetch user invalid")
        // => errors.Is can inspect wrapped error
        // => CRITICAL: %w not %v (only %w wraps)
    }
 
    return nil
    // => Success case
}
 
func processUser(id string) error {
    // => Calls fetchUser and adds more context
 
    err := fetchUser(id)
    // => err might be wrapped ErrNotFound
 
    if err != nil {
        // => Error occurred in fetchUser
 
        return fmt.Errorf("processUser: %w", err)
        // => Wrap again with additional context
        // => Error chain: processUser → fetchUser → ErrNotFound
        // => Each layer adds context
    }
 
    return nil
}
 
func main() {
    err := processUser("invalid")
    // => err is wrapped error chain
 
    if err != nil {
        fmt.Println("Error:", err)
        // => Output: Error: processUser: failed to fetch user invalid: not found
        // => Full error chain printed
 
        // CHECK ERROR IDENTITY with errors.Is
        if errors.Is(err, ErrNotFound) {
            // => errors.Is unwraps error chain
            // => Checks if any error in chain is ErrNotFound
            // => Returns true even through multiple wraps
 
            fmt.Println("User not found!")
            // => Output: User not found!
            // => Specific handling for not found case
        }
    }
}

Pattern: Error Type Inspection with errors.As:

package main
 
import (
    "errors"
    // => Standard library for errors.As
    "fmt"
)
 
// Custom error type with additional fields
type NetworkError struct {
    StatusCode int
    // => HTTP status code
    URL        string
    // => URL that failed
    Err        error
    // => Underlying error (wrapped)
}
 
func (e *NetworkError) Error() string {
    // => Implements error interface
 
    return fmt.Sprintf("network error %d for %s: %v", e.StatusCode, e.URL, e.Err)
    // => Formatted error message
}
 
func (e *NetworkError) Unwrap() error {
    // => Unwrap enables errors.Is/As to inspect chain
    // => Returns wrapped error
    // => CRITICAL: implement for error wrapping to work
 
    return e.Err
}
 
func fetchData(url string) error {
    // => Simulates HTTP request
 
    if url == "http://example.com/error" {
        // => Simulate 404 error
 
        return &NetworkError{
            StatusCode: 404,
            URL:        url,
            Err:        errors.New("page not found"),
        }
        // => Returns custom error with context
    }
 
    return nil
}
 
func main() {
    err := fetchData("http://example.com/error")
    // => err is *NetworkError
 
    if err != nil {
        // => Error occurred
 
        var netErr *NetworkError
        // => Declare variable for error type
        // => Must be pointer to match error type
 
        if errors.As(err, &netErr) {
            // => errors.As checks if err is *NetworkError
            // => Unwraps error chain to find matching type
            // => Assigns found error to netErr
            // => Returns true if found
 
            fmt.Printf("Network error: status=%d, url=%s\n",
                netErr.StatusCode, netErr.URL)
            // => Output: Network error: status=404, url=http://example.com/error
            // => Access NetworkError-specific fields
 
            if netErr.StatusCode == 404 {
                // => Type-specific handling
                fmt.Println("Resource not found")
                // => Output: Resource not found
            }
        }
    }
}

Pattern: Sentinel Errors vs Custom Error Types:

package main
 
import (
    "errors"
    "fmt"
)
 
// SENTINEL ERRORS: for simple cases
var (
    ErrInvalidInput = errors.New("invalid input")
    // => Predefined error (identity checking)
    ErrTimeout      = errors.New("operation timed out")
    // => Simple error without additional data
    ErrUnauthorized = errors.New("unauthorized")
)
 
// CUSTOM ERROR TYPE: when additional context needed
type DatabaseError struct {
    Query     string
    // => SQL query that failed
    Table     string
    // => Table name
    Err       error
    // => Underlying error
}
 
func (e *DatabaseError) Error() string {
    return fmt.Sprintf("database error on table %s: %v (query: %s)",
        e.Table, e.Err, e.Query)
}
 
func (e *DatabaseError) Unwrap() error {
    return e.Err
}
 
func queryUser(id string) error {
    // => Simulates database query
 
    if id == "" {
        // => Input validation
 
        return fmt.Errorf("queryUser: %w", ErrInvalidInput)
        // => Sentinel error wrapped with context
        // => Simple case: no additional fields needed
    }
 
    if id == "timeout" {
        // => Simulate database timeout
 
        return &DatabaseError{
            Query: "SELECT * FROM users WHERE id = ?",
            Table: "users",
            Err:   ErrTimeout,
        }
        // => Custom error with context
        // => Additional fields (Query, Table)
    }
 
    return nil
}
 
func main() {
    // Sentinel error case
    err1 := queryUser("")
    if errors.Is(err1, ErrInvalidInput) {
        // => errors.Is checks sentinel error
        fmt.Println("Invalid input detected")
        // => Output: Invalid input detected
    }
 
    // Custom error type case
    err2 := queryUser("timeout")
 
    var dbErr *DatabaseError
    if errors.As(err2, &dbErr) {
        // => errors.As extracts custom error type
 
        fmt.Printf("Database error: table=%s, query=%s\n",
            dbErr.Table, dbErr.Query)
        // => Output: Database error: table=users, query=SELECT * FROM users WHERE id = ?
        // => Access error-specific context
 
        if errors.Is(dbErr.Err, ErrTimeout) {
            // => Check wrapped sentinel error
            fmt.Println("Query timed out - retry later")
            // => Output: Query timed out - retry later
        }
    }
}

Trade-offs: When to Use Each

Comparison table:

Approach	Context Preservation	Type Safety	Use Case
errors.New()	None	Runtime	Simple errors (no wrapping)
fmt.Errorf %w	Full chain	Runtime	Wrapping with context
Sentinel errors	Identity	Compile-time	Expected errors (ErrNotFound)
Custom types	Rich context	Compile-time	Errors with additional data

When to use errors.New():

Simple error messages
No error wrapping needed
Leaf errors (not wrapped further)
Quick error returns

When to use fmt.Errorf with %w:

Adding context to existing errors
Building error chains through call stack
Preserving original error for errors.Is/As
Most common pattern in production

When to use sentinel errors:

Expected errors with known identity (ErrNotFound, ErrTimeout)
API boundaries (exported errors)
Error equality checks
Simple cases without additional context

When to use custom error types:

Errors with additional fields (StatusCode, URL, Query)
Type-specific error handling
Rich error context for debugging
Complex error cases

Production Best Practices

Always wrap errors with context:

// GOOD: wrap with %w (preserves chain)
if err := fetchUser(id); err != nil {
    return fmt.Errorf("failed to fetch user %s: %w", id, err)
}
 
// BAD: lose error chain with %v
if err := fetchUser(id); err != nil {
    return fmt.Errorf("failed to fetch user %s: %v", id, err)
    // %v converts to string (loses error identity)
}

Use errors.Is for sentinel error checking:

// GOOD: errors.Is unwraps chain
if errors.Is(err, ErrNotFound) {
    // Handle not found
}
 
// BAD: direct comparison fails with wrapping
if err == ErrNotFound {
    // Won't match if err is wrapped
}

Use errors.As for type inspection:

// GOOD: errors.As extracts type from chain
var netErr *NetworkError
if errors.As(err, &netErr) {
    // Use netErr fields
}
 
// BAD: type assertion fails with wrapping
if netErr, ok := err.(*NetworkError); ok {
    // Won't work if err is wrapped
}

Implement Unwrap() for custom error types:

// GOOD: Unwrap enables errors.Is/As
type MyError struct {
    Err error
}
 
func (e *MyError) Unwrap() error {
    return e.Err  // Enable error chain inspection
}
 
// BAD: no Unwrap (breaks error chain)
type MyError struct {
    Err error
}
// errors.Is/As won't inspect wrapped errors

Don't panic for expected errors:

// GOOD: return error
func parseConfig(data []byte) (*Config, error) {
    if len(data) == 0 {
        return nil, ErrInvalidConfig
    }
    // ...
}
 
// BAD: panic for expected errors
func parseConfig(data []byte) *Config {
    if len(data) == 0 {
        panic("invalid config")  // Don't panic
    }
    // ...
}

Summary

Go's explicit error handling forces errors to be visible at call sites. Standard library provides error interface and errors.New() for simple errors. Go 1.13+ adds error wrapping with fmt.Errorf %w, errors.Is for identity checking, and errors.As for type inspection. Use sentinel errors for simple cases, custom types for rich context, and always wrap errors to preserve error chains.

Key takeaways:

error is interface with Error() string method
Wrap errors with fmt.Errorf %w to preserve chain
Use errors.Is to check sentinel errors through wrapping
Use errors.As to extract custom error types
Implement Unwrap() for custom error types
Return errors (don't panic) for expected failures