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) }

Verb Effect

%w

Wraps error — errors.Is / errors.As can unwrap

%v

Formats error — wrapping chain is lost

When to Wrap vs Not

Scenario Action Why

Adding context fmt.Errorf("...: %w", err)

Preserves chain for callers

Hiding implementation detail fmt.Errorf("...: %v", err) or new error Don't leak internal types

Matching sentinel errors Use %w

Callers can errors.Is

Library boundary Consider carefully Wrapping couples caller to your dependencies

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 }

Sentinel rule Detail

Name with Err prefix ErrNotFound , ErrTimeout

Package-level var

Not const — must be comparable with errors.Is

Use sparingly Only for errors callers need to check programmatically

Document them Part of your API contract

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 }

Panic rule Detail

Only for programmer errors Impossible states, violated invariants

Never for expected failures Network errors, file not found → return error

Must prefix convention MustCompile , MustParse — panics on error

Acceptable in init()

If package cannot initialize

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) }

Recover rule Detail

Only in deferred functions recover() returns nil outside defer

Stops unwinding Returns panic value

Use at goroutine/request boundary Prevent one failure from crashing server

Always log the panic With stack trace (debug.Stack() )

Don't recover to hide bugs Fix the root cause

Common Mistakes

Mistake Why Bad Fix

_ = f.Close()

Silently loses write errors if err := f.Close(); err != nil { ... }

panic for expected errors Crashes program Return error

Not wrapping errors Lost context fmt.Errorf("context: %w", err)

Comparing errors with ==

Doesn't check wrapped chain errors.Is(err, target)

Type-asserting errors directly Doesn't check wrapped chain errors.As(err, &target)

Wrapping with %v when %w intended Breaks errors.Is / errors.As

Use %w for wrapping

Error strings starting with capital Convention violation Lowercase: "opening file: ..."

Error strings ending with punctuation Doesn't compose well No period: "not found" not "not found."

if err != nil { return err } everywhere Lost context Add wrapping message

Returning error AND valid value Confusing API If err != nil , zero-value the result