07 - Errors¶

What this session is¶

About an hour. You'll learn how Go handles things going wrong - opening a file that doesn't exist, parsing a number from text that isn't a number, network calls that fail. Go's approach is different from most other languages and one of the things that makes Go code recognizable on sight.

The big idea: errors are values¶

In many languages (Python, Java, JavaScript, Ruby), when something goes wrong the language throws an exception that flies up the call stack until someone catches it. If nobody catches it, the program crashes.

Go does not do this. In Go, a function that can fail returns an extra value: an error. The caller is expected to check it.

result, err := SomethingThatCanFail()
if err != nil {
    // handle the failure
    return err
}
// use result, now that we know it's safe

That if err != nil { ... } block is the most-typed pattern in all of Go. Some people love it; some people complain about it. Either way, you can't read Go code without it.

A real example¶

The standard library has strconv.Atoi, which converts a string to an integer ("Atoi" = "ASCII to integer"). It might fail, because "hello" isn't a number. So it returns two things:

package main

import (
    "fmt"
    "strconv"
)

func main() {
    n, err := strconv.Atoi("42")
    if err != nil {
        fmt.Println("could not parse:", err)
        return
    }
    fmt.Println("got the number:", n)

    n2, err := strconv.Atoi("hello")
    if err != nil {
        fmt.Println("could not parse:", err)
        return
    }
    fmt.Println("got the number:", n2)   // never reached
}

Type and run. Output:

got the number: 42
could not parse: strconv.Atoi: parsing "hello": invalid syntax

What's happening:

• strconv.Atoi("42") succeeds. err is nil (the special "nothing" value). We skip the if and use n.
• strconv.Atoi("hello") fails. err is a non-nil error value with a useful message. We enter the if, print it, and return from main - which ends the program.

That nil thing is new. nil is Go's word for "no value, nothing here." When a function returns (T, error):

• If everything was fine: the T is the real result and error is nil.
• If something failed: the T is usually the zero value (don't trust it), and error is the actual error.

You always check err != nil before trusting the other return value. Always. There are no exceptions to this rule for code you write.

What is an error, exactly? (the mental model)¶

Here's the part of Go that surprises people coming from other languages: error has almost no magic in it. The entire error type is defined like this in the standard library:

type error interface {
    Error() string
}

That's it. An error is any type that has a method called Error() returning a string. No special inheritance, no exception class to extend, no throws annotation, nothing. If your type has an Error() string method, your type IS an error and the compiler will accept it where an error is expected.

This is what people mean when they say "errors are values." Errors aren't a special control-flow mechanism - they're just regular values implementing a regular interface. You can store them in slices, send them through channels, compare them, pass them to functions, return them - anything you can do with any other value.

You met interfaces formally on page 05. The short version: an interface is a contract. The error contract is "I can tell you a string about what went wrong."

Here's the entire mechanism, demonstrated in one program:

package main

import "fmt"

// MyError is a custom error type - just a struct with an Error() method.
type MyError struct {
    Code int
    Msg  string
}

func (e *MyError) Error() string {
    return fmt.Sprintf("[%d] %s", e.Code, e.Msg)
}

func doStuff() error {
    return &MyError{Code: 404, Msg: "not found"}
}

func main() {
    err := doStuff()
    fmt.Println(err)              // [404] not found
    fmt.Println(err.Error())      // [404] not found  -- same thing
    fmt.Println(err == nil)       // false
}

fmt.Println(err) automatically calls err.Error() to get a string to print. There's no magic - just the interface contract being satisfied.

This means errors can carry any structured data you want. Want an error that knows an HTTP status code? Add a Status int field. Want one that knows which field failed validation? Add a Field string. The error is a regular struct; you can put anything in it. The caller can inspect it (you'll see how, in Going deeper).

Try it: 1. Type the program above. Confirm both prints show [404] not found.

1. Add a second method: func (e *MyError) IsRetryable() bool { return e.Code >= 500 }. Inside main, do if me, ok := err.(*MyError); ok && me.IsRetryable() { ... }. (You're doing a type assertion - checking if err is actually a *MyError underneath.)

2. Try returning errors.New("simple") instead of &MyError{...}. What changes? (Hint: errors.New returns an unexported type with just an Error() method.)

Making your own errors¶

You'll write functions that can fail. They need to return errors.

The simplest way:

import "errors"

func divide(a, b int) (int, error) {
    if b == 0 {
        return 0, errors.New("divide by zero")
    }
    return a / b, nil
}

errors.New("...") creates a brand-new error with the given message. Use it for simple cases.

The fancier way uses fmt.Errorf, which is like fmt.Sprintf but produces an error:

import "fmt"

func divide(a, b int) (int, error) {
    if b == 0 {
        return 0, fmt.Errorf("cannot divide %d by zero", a)
    }
    return a / b, nil
}

The advantage: you can include variables in the error message, exactly like Println.

Wrapping errors with %w¶

Often a function fails because another function it called failed. You want to include the deeper error in your own error message:

import (
    "fmt"
    "strconv"
)

func parseAge(input string) (int, error) {
    n, err := strconv.Atoi(input)
    if err != nil {
        return 0, fmt.Errorf("parsing age %q: %w", input, err)
    }
    if n < 0 {
        return 0, fmt.Errorf("age cannot be negative, got %d", n)
    }
    return n, nil
}

The %w placeholder wraps the original error inside your new one. Why this matters:

• The error message includes everything: "parsing age \"hello\": strconv.Atoi: parsing \"hello\": invalid syntax". Helpful when debugging.
• Other code can later unwrap it (errors.Is, errors.As) to check whether a specific underlying error happened. You'll see this in real codebases.

For now, the rule: when you return an error that was caused by another error, wrap it with %w.

The wrap chain (the mental model)¶

Each %w wrap creates a new error that points at the inner error - like a linked list:

your error  ──Unwrap()──▶  intermediate error  ──Unwrap()──▶  original error  ──Unwrap()──▶  nil
"validating config"        "parsing line 12"                  "unexpected '}' at col 5"

This is how the chain actually works in the runtime. A wrapped error is a struct with two fields: a message and an inner error. Its Unwrap() method returns the inner error. Call Unwrap() repeatedly and you walk back through the whole history until you hit nil.

You almost never call Unwrap() directly. Two helpers in the errors package walk the chain for you:

import "errors"

// Is the original error (or anything in the chain) a specific sentinel?
if errors.Is(err, io.EOF) { ... }

// Is the original error (or anything in the chain) a specific type?
var pathErr *os.PathError
if errors.As(err, &pathErr) {
    fmt.Println("bad path:", pathErr.Path)
}

errors.Is walks the chain and returns true if any link in it equals the target. errors.As walks the chain and returns true if any link in it is the requested type (and fills in the pointer with it).

Run the wrap-chain demo yourself:

package main

import (
    "errors"
    "fmt"
)

var ErrNotFound = errors.New("not found")

func main() {
    inner := fmt.Errorf("lookup user 42: %w", ErrNotFound)
    outer := fmt.Errorf("load profile: %w", inner)

    fmt.Println(outer)
    // load profile: lookup user 42: not found

    fmt.Println(errors.Unwrap(outer))
    // lookup user 42: not found

    fmt.Println(errors.Unwrap(errors.Unwrap(outer)))
    // not found

    fmt.Println(errors.Is(outer, ErrNotFound))
    // true   -- errors.Is walked the entire chain
}

That last line is the whole point. Even though outer is two levels of wrapping above ErrNotFound, errors.Is(outer, ErrNotFound) returns true because it walked the chain. You compare against the root cause; you don't have to know how deep it's buried.

Try it: 1. Type the program. Confirm the output.

1. Replace one %w with %v and re-run. What does errors.Is(outer, ErrNotFound) return now? Why? (Hint: %v doesn't wrap; it just flattens to a string. The chain breaks at that point.)

2. Define a second sentinel var ErrTemporary = errors.New("temporary"). Wrap both into a single error with errors.Join(ErrNotFound, ErrTemporary). Check errors.Is against each - both return true. (You'll see errors.Join again in Going deeper.)

The pattern, end-to-end¶

A function that does several things, any of which can fail:

func loadConfig(path string) (Config, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        return Config{}, fmt.Errorf("reading %s: %w", path, err)
    }

    cfg, err := parseConfig(data)
    if err != nil {
        return Config{}, fmt.Errorf("parsing %s: %w", path, err)
    }

    if err := cfg.Validate(); err != nil {
        return Config{}, fmt.Errorf("validating %s: %w", path, err)
    }

    return cfg, nil
}

Three things, three if err != nil blocks, three wrapped error messages. Every error tells you which step failed and what happened underneath. This shape - try a step, check, maybe wrap and return - is the rhythm of Go.

It is verbose. People who come from exception-based languages often dislike this initially. The argument for it: every failure path is right there in the code, visible and explicit, not hidden in a throws clause or a catch block somewhere else.

What about panics, and why no exceptions?¶

You'll occasionally see panic("message") in Go code. A panic is a program-level crash - used for "this should never happen, the program is broken." Examples: dividing by zero (the language panics for you), trying to read index 99 of a 3-element slice, dereferencing a nil pointer.

Don't use panic for normal failure cases. "File not found" isn't a panic; it's an error. Panic is for "the world is broken and there's no recovering." You'll see it in init code (a service can't start without its config) and in development assertions ("this case should be impossible - if it happens, I want to know loudly").

There's a way to catch panics (recover) but you'll almost never need it. Use errors for almost everything.

Why doesn't Go just use exceptions? Worth a moment because it explains the if-err-not-nil discipline.

Exception-based languages (Python, Java, JavaScript) treat failures as a separate control-flow channel: a function that raises an exception transfers control to whatever try/catch is nearest up the stack - invisibly, from the calling code's point of view. The advantages are concise happy-path code and centralized error handling. The disadvantages are that:

1. Every function call is potentially an unexpected exit point. You can't tell by reading the code what might throw.
2. The control flow is hidden. A function 10 frames down can raise an exception that resurfaces in a handler you wrote without knowing about that function.
3. Resource cleanup is fragile without language support like try-with-resources or using blocks.

Go's authors decided that the tradeoff was wrong: the verbosity of if err != nil is worth paying for control flow that's visible at the call site. Every place a function might fail is right there in the code. There are no surprise exits.

You don't have to agree with the choice. You do have to live with it when you write Go.

(Panic exists for the cases exceptions handle in other languages - truly unrecoverable program bugs. The difference is that Go strongly discourages routinely using it. Errors are the default mechanism; panic is the escape hatch.)

Try it: 1. Trigger a panic deliberately: arr := []int{1, 2, 3}; fmt.Println(arr[10]). Run it. Read the stack trace.

1. Compare with what happens when you forget to handle an error: replace your if err != nil block with just _ = err. The program may keep running on bad data, producing wrong results silently. Which failure mode would you rather debug - the loud crash with a stack trace, or the silent corruption?

package mystore

import "errors"

var ErrNotFound = errors.New("item not found")

func Lookup(id string) (Item, error) {
    if id == "" {
        return Item{}, ErrNotFound
    }
    // ...
}

item, err := store.Lookup(id)
if errors.Is(err, mystore.ErrNotFound) {
    // handle "not found" specifically
    return nil
}
if err != nil {
    return err
}

type ValidationError struct {
    Field   string
    Message string
}

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

err := DoStuff()
var ve *ValidationError
if errors.As(err, &ve) {
    fmt.Println("bad field:", ve.Field)
    fmt.Println("message:   ", ve.Message)
}

type Error struct {
    Path string
    User string
}

func (e *Error) Error() string {
    return fmt.Sprintf("error path=%s user=%s", e.Path, e.User)
}

// "Template match": non-zero target fields must match.
func (e *Error) Is(target error) bool {
    t, ok := target.(*Error)
    if !ok {
        return false
    }
    return (t.Path == "" || e.Path == t.Path) &&
           (t.User == "" || e.User == t.User)
}

err := &Error{Path: "/etc/shadow", User: "alice"}
errors.Is(err, &Error{User: "alice"})           // true  -- User matches; Path ignored
errors.Is(err, &Error{Path: "/etc/shadow"})     // true  -- Path matches; User ignored
errors.Is(err, &Error{User: "bob"})             // false

// Looks pointless, but isn't:
if !userHasPermission(u) {
    return fmt.Errorf("%w", ErrPermission)
}

// Caller-A using == (works only because ErrPermission was returned directly):
if err == mypkg.ErrPermission { ... }

// Caller-B using errors.Is (works regardless of wrapping):
if errors.Is(err, mypkg.ErrPermission) { ... }

package net

type Error interface {
    error
    Timeout() bool      // Is the failure a timeout?
    Temporary() bool    // Is the failure temporary (retry might succeed)?
}

if nerr, ok := err.(net.Error); ok && nerr.Temporary() {
    time.Sleep(time.Second)
    continue   // retry
}

type retryable interface {
    Retryable() bool
}

// In your package:
type myErr struct{ msg string; retry bool }
func (e *myErr) Error() string   { return e.msg }
func (e *myErr) Retryable() bool { return e.retry }

// In any caller:
var r retryable
if errors.As(err, &r) && r.Retryable() {
    // retry
}

import "errors"

func processAll(items []Item) error {
    var errs []error
    for _, item := range items {
        if err := process(item); err != nil {
            errs = append(errs, err)
        }
    }
    return errors.Join(errs...)   // nil if errs is empty
}

err := errors.Join(ErrTimeout, ErrNotFound)
errors.Is(err, ErrTimeout)    // true
errors.Is(err, ErrNotFound)   // true
fmt.Println(err)
// timeout
// not found

Exercise¶

In a new file parse.go:

Write a function parsePositive(s string) (int, error) that:

1. Parses s as an integer using strconv.Atoi.
2. If Atoi fails, returns the error wrapped with %w and a message like "parsePositive %q: %w".
3. If the parsed number is less than or equal to zero, returns an error like "parsePositive: number must be positive, got %d" (use fmt.Errorf, no wrap because there's no underlying error to wrap).
4. If everything is fine, returns the number and nil.

In main, call parsePositive with each of these inputs and print the result: - "42" → expect 42, no error - "hello" → expect parse error - "-5" → expect "must be positive" error - "0" → expect "must be positive" error - "100" → expect 100, no error

Loop over them with a slice: inputs := []string{"42", "hello", "-5", "0", "100"}.

What you might wonder¶

"Why isn't this try/catch like other languages?" Design choice. Exceptions hide control flow - a function call may secretly jump to a handler 10 frames up the stack. Go's authors decided that making every failure path explicit was worth the extra typing. You don't have to agree with the choice; you do have to read the code.

"What's nil?" Go's "no value" for types that can be absent - errors, pointers (page 08), maps that haven't been made yet, slices that haven't been initialized, channels. nil compared with == lets you check for "nothing here." if err != nil literally means "if there is an error."

"Is if err != nil really every other line?" Roughly, yes. Modern Go has a few patterns to reduce it (helpers, error groups), but expect to see and write the pattern often. You'll stop noticing it in a few weeks.

"What's %q?" A fmt placeholder that prints a value in quoted form: "hello" rather than hello. Useful in error messages so you can tell whitespace and empty strings apart.

Done¶

You can now: - Recognize that Go functions that can fail return (T, error). - Write the if err != nil { return ..., err } pattern. - Create errors with errors.New and fmt.Errorf. - Wrap one error inside another with %w. - Tell errors apart from panics (and know when to use each).

You've now seen Go's most distinctive idiom. Real Go code is mostly: data shaping (slices, maps, structs), decisions and loops, function composition, and error checking. You have all five.

Next page: pointers - how Go lets you share data and let functions mutate things.

Next: Pointers and memory → 08-pointers-and-memory.md

Comments