Go Error Handling

Core Principle

Errors are values in Go. Handle them explicitly — don’t hide them, don’t panic for expected failures.

Error Interface

type error interface {
    Error() string
}

Creating Errors

// Simple errors
import "errors"
var ErrNotFound = errors.New("not found")

// Formatted errors
import "fmt"
return fmt.Errorf("user %d not found", id)

// Wrapped errors (Go 1.13+) — preserves cause chain
return fmt.Errorf("fetching user: %w", err)

// Custom error type
type ValidationError struct {
    Field   string
    Message string
}

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

Error Wrapping & Unwrapping

// Wrap with context
if err := db.Query(sql); err != nil {
    return fmt.Errorf("querying users: %w", err)
}

// errors.Is — check for specific error in chain
if errors.Is(err, sql.ErrNoRows) {
    return nil, ErrNotFound
}

// errors.As — extract specific error type from chain
var pathErr *os.PathError
if errors.As(err, &pathErr) {
    fmt.Println("Failed at path:", pathErr.Path)
}

When to Wrap vs Not

Sentinel Errors

// Package-level error values
var (
    ErrNotFound     = errors.New("not found")
    ErrUnauthorized = errors.New("unauthorized")
    ErrConflict     = errors.New("conflict")
)

// Usage
func FindUser(id int) (*User, error) {
    user, err := db.Get(id)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return nil, ErrNotFound
        }
        return nil, fmt.Errorf("finding user %d: %w", id, err)
    }
    return user, nil
}

Custom Error Types

type NotFoundError struct {
    Resource string
    ID       int
}

func (e *NotFoundError) Error() string {
    return fmt.Sprintf("%s %d not found", e.Resource, e.ID)
}

// Optional: wrap underlying error
type QueryError struct {
    Query string
    Err   error
}

func (e *QueryError) Error() string {
    return fmt.Sprintf("query %q: %v", e.Query, e.Err)
}

func (e *QueryError) Unwrap() error {
    return e.Err  // enables errors.Is/errors.As
}

Errors as Values

Errors are programmable values — use patterns to reduce repetitive if err != nil:

// ErrorWriter: accumulates error, check once at end
type ErrorWriter struct {
    w   io.Writer
    err error
}

func (ew *ErrorWriter) Write(buf []byte) {
    if ew.err != nil { return }
    _, ew.err = ew.w.Write(buf)
}

// Usage — chain writes, check once
ew := &ErrorWriter{w: w}
ew.Write(header)
ew.Write(body)
ew.Write(footer)
if ew.err != nil {
    return ew.err
}

No In-Band Errors

// BAD: -1 or empty string as error signal
func Lookup(key string) string {
    if _, ok := m[key]; !ok { return "" }  // "" might be valid!
    return m[key]
}

// GOOD: return additional value
func Lookup(key string) (string, bool) {
    v, ok := m[key]
    return v, ok
}

// GOOD: return error
func Lookup(key string) (string, error) {
    v, ok := m[key]
    if !ok { return "", ErrNotFound }
    return v, nil
}

Handle Every Error

// BAD: silently ignored
f.Close()

// GOOD: handle or explicitly acknowledge
if err := f.Close(); err != nil {
    log.Printf("closing file: %v", err)
}

// OK: documented why it's safe to ignore
n, _ := buf.Write(data) // bytes.Buffer.Write never returns error

Handling Patterns

The Standard Pattern

result, err := doSomething()
if err != nil {
    return fmt.Errorf("doing something: %w", err)
}
// use result

Multiple Cleanup Actions

func process() (err error) {
    f, err := os.Open("file.txt")
    if err != nil {
        return err
    }
    defer f.Close()

    w, err := os.Create("output.txt")
    if err != nil {
        return err
    }
    defer func() {
        closeErr := w.Close()
        if err == nil {
            err = closeErr  // capture close error if no prior error
        }
    }()

    _, err = io.Copy(w, f)
    return err
}

Error Type Switch

switch err := err.(type) {
case nil:
    // success
case *ValidationError:
    http.Error(w, err.Message, http.StatusBadRequest)
case *NotFoundError:
    http.Error(w, err.Error(), http.StatusNotFound)
default:
    log.Printf("unexpected error: %v", err)
    http.Error(w, "internal error", http.StatusInternalServerError)
}

Panic & Recover

Panic

// Panic for truly unrecoverable situations
func MustCompile(pattern string) *Regexp {
    re, err := Compile(pattern)
    if err != nil {
        panic("regexp: Compile(" + pattern + "): " + err.Error())
    }
    return re
}

Recover

func safeHandler(w http.ResponseWriter, r *http.Request) {
    defer func() {
        if err := recover(); err != nil {
            log.Printf("panic recovered: %v\n%s", err, debug.Stack())
            http.Error(w, "internal error", http.StatusInternalServerError)
        }
    }()
    handleRequest(w, r)
}

Common Mistakes