Chapter 14: Error Handling in Concurrent Code

14.1 The Fundamental Problem

In sequential code the error path is the return path, and it is always there. In concurrent code it is neither.

14.1.1 The go Keyword Severs the Error Chain

// Illustrative snippet — not a complete program
func compute() (int, error) { return 42, nil }

result, err := compute() // blocks; both values arrive
go compute()             // compiles; (42, nil) is discarded

The values are not hidden somewhere for later retrieval. The runtime never captures them, because there is no frame waiting to receive them. This is not an oversight in the language design; it follows from what go means. Return values require the caller to wait. go is the statement that says do not wait. You cannot have both, so Go gives you the second and leaves the first to you.

Three consequences follow, and none of them exist in sequential code:

• No caller to return to. By the time the goroutine fails, the function that started it may have returned.
• No ordering among failures. Launch ten, have three fail — which error is the error? The first by wall clock? By scheduling? All three? Sequential code never has to answer this, because only one path runs at a time.
• No lineage. The runtime tracks no parent-child relationship between goroutines, so nothing propagates automatically. There is no mechanism to inherit.

14.1.2 The Silent Failure

Here is the failure mode that makes this worth a chapter:

// Illustrative snippet — not a complete program
func main() {
    records := []string{"order-1", "order-2", "order-3"}
    for _, id := range records {
        go process(id)
    }
    time.Sleep(time.Second) // not production-safe; see §2.3
    fmt.Println("all orders processed successfully")
}

func process(id string) error {
    if id == "order-2" {
        return errors.New("payment gateway timeout")
    }
    fmt.Printf("  ok %s processed\n", id)
    return nil
}

Two of the three lines print, in an order that changes between runs, and then the program announces complete success:

process returned an error to nobody. The program did not crash, did not log, did not return a non-nil error to its caller. It reported success for work that failed, which is the most expensive kind of bug: it compounds silently, and the incident arrives days later attached to the wrong symptom.

14.1.3 What Doesn’t Work

Four things look like answers and are not.

Logging instead of propagating. log.Printf("failed: %v", err) inside the goroutine records the failure for a human reading later. The calling code still needs to retry, return 500, or fall back — and it cannot, because nothing told it. Logging is observability; it is not error handling.

Panicking. A panic in a goroutine is not contained to that goroutine. Unless it is recovered on that same stack, it takes the whole process down (§14.6). This trades a silent failure for a catastrophic one.

A shared error variable. lastErr = err from several goroutines is a data race (§8.2), and it keeps one error out of however many occurred.

Ignoring it. go process(order) compiles. Networks fail, disks fill, services restart. The errors happen whether or not you built somewhere for them to go.

14.1.4 Three Solutions

Each of the three builds the return path in a different shape.

Error channels (§14.2). A dedicated chan error. The goroutine sends, the caller receives. No dependencies, no new types, and full control over how many errors you collect and what you do with them. Best when the goroutine’s job is a side effect and the only question is whether it worked.

// Illustrative snippet — not a complete program
errCh := make(chan error, 1)
go func() { errCh <- sendEmail(to, "Welcome!") }()
if err := <-errCh; err != nil {
    return fmt.Errorf("welcome email: %w", err)
}

Result structs (§14.3). One struct carrying the value, the error, and an identifier, sent on one channel. Best when the goroutine produces something the caller needs, and when you need to know which goroutine produced which outcome.

// Illustrative snippet — not a complete program
type FetchResult struct {
    URL  string
    Body []byte
    Err  error
}

ch := make(chan FetchResult, len(urls))

errgroup (§14.4). golang.org/x/sync/errgroup wraps a WaitGroup, a sync.Once and a cancel function into three calls. Best when you want the first error to stop the rest.

// Illustrative snippet — not a complete program
g, ctx := errgroup.WithContext(ctx)
g.Go(func() error { return sendEmail(ctx, to, "Welcome!") })
g.Go(func() error { return sendSMS(ctx, num, "Welcome!") })
if err := g.Wait(); err != nil {
    return err
}

14.1.5 Choosing the Right Mechanism

Does the goroutine produce a value you need?
  │
  ├─ yes ─────────────────────► Result struct (§14.3)
  │                             identity + value + error
  └─ no
      │
      ├─ one or two goroutines ─► chan error (§14.2)
      │
      ├─ a batch, first error
      │  should stop the rest ──► errgroup (§14.4)
      │
      └─ long-lived workers
         reporting as they go ──► chan error (§14.2)

These compose. errgroup for the lifecycle and a result
slice for the output is the most common production
shape (§14.4.6).

The three are not exclusive, and the table is not a decision you make once. Production code routinely uses errgroup for coordination with result structs for output, which is why §14.4.6 exists.

14.1.6 Common Mistakes

Summary: The Fundamental Problem

The go keyword discards return values because a caller that does not wait cannot receive them. That is not a flaw to work around but the definition of the statement, and it means every goroutine that can fail needs an explicit path back to code that can act on the failure.

The failure mode is silence. Nothing crashes and nothing logs; the program simply reports an outcome that did not happen. Logging inside the goroutine does not fix it, because logs are read by people afterwards and the caller needs to react now.

Three mechanisms build the path. An error channel carries errors only. A result struct carries a value, an error and an identity together. errgroup carries the first error and cancels the rest. Which one you want depends on whether the goroutine produces a value, how many goroutines there are, and whether one failure should stop the others.

Self-Check Questions: The Fundamental Problem

14.2 Error Channels

The most direct answer to §14.1 is the one with no new concepts in it: give the goroutine a chan error and receive from it. Everything hard about this pattern is a sizing decision, and every sizing decision is about whether a send can block.

14.2.1 The Basic Pattern

// Illustrative snippet — not a complete program
func sendWelcomeEmail(to string) error {
    errCh := make(chan error, 1) // one sender, one slot

    go func() {
        errCh <- sendEmail(to, "Welcome!") // always sends
    }()

    prepareUserDashboard() // useful work while the mail goes out

    if err := <-errCh; err != nil {
        return fmt.Errorf("welcome email: %w", err)
    }
    return nil
}

Two decisions are doing all the work here.

Always send. The goroutine sends the result of sendEmail unconditionally — nil on success, an error on failure. The receiver does <-errCh, which blocks until something arrives. If the goroutine only sent on failure, a successful send of nothing would leave the caller blocked forever. One goroutine, one send, on every path.

Buffer of one. The goroutine can deposit its result and exit without waiting for anyone to collect it. Whether that matters depends on whether the receiver can leave early, which is the whole of §14.2.2.

14.2.2 Buffered vs Unbuffered

An unbuffered channel requires a sender and a receiver to meet. If the receiver can stop waiting — a select with another case, an early return, a timeout — the sender is left holding a value nobody will take.

Failure mode one: the leak.

// Illustrative snippet — not a complete program
func checkEndpoint(ctx context.Context, url string) error {
    errCh := make(chan error) // ✗ unbuffered

    go func() {
        errCh <- httpPing(url) // blocks until someone receives
    }()

    select {
    case err := <-errCh:
        return err
    case <-ctx.Done():
        return ctx.Err() // we leave; the goroutine never can
    }
}

When the deadline fires first, checkEndpoint returns and stops receiving. The ping eventually completes, the goroutine reaches its send, and parks there permanently. One leaked goroutine per timeout, each holding its stack and whatever the request referenced.

Failure mode two: the deadlock.

// Illustrative snippet — not a complete program
// ✗ WRONG: unbuffered channel and a WaitGroup
func process(items []Item) error {
    var wg sync.WaitGroup
    errCh := make(chan error) // unbuffered

    for _, item := range items {
        wg.Go(func() {
            if err := processItem(item); err != nil {
                errCh <- err // blocks; wg.Done never runs
            }
        })
    }

    wg.Wait()  // waits for goroutines that are waiting for us
    close(errCh)
    return <-errCh
}

If nothing fails this runs fine, which is what makes it dangerous — it passes every test with valid input. The first real error deadlocks it. The goroutine blocks on the send before wg.Go's implicit Done can run, and the main goroutine is inside wg.Wait rather than receiving.

main                worker 1            worker 2
 │                     │                   │
 │ wg.Wait()      processItem()       processItem()
 │   blocked           │                   │
 │                  err occurs          err occurs
 │                     │                   │
 │              errCh <- err          errCh <- err
 │               blocked: no           blocked: no
 │                receiver              receiver
 │                     │                   │
 │              never reaches         never reaches
 │                 Done()                Done()
 │
 └─► main waits for workers.
     Workers wait for main to receive.

Both failure modes have the same fix, and it is the same
rule as §5.2: size the buffer so a send can always complete.

The rule. For N goroutines each sending once on one channel, buffer to N:

// Illustrative snippet — not a complete program
errCh := make(chan error, len(items))

Then every send completes immediately into the buffer, every goroutine exits, and the receiver collects at its leisure — or does not collect at all, and the channel is garbage collected with the values still in it.

14.2.3 Collecting Errors from Multiple Goroutines

With every goroutine sending exactly once, the receiver knows exactly how many receives to do. That count is the termination condition — no close, no WaitGroup, no closer goroutine.

First error wins:

// Illustrative snippet — not a complete program
func validateAll(items []Item) error {
    errCh := make(chan error, len(items))

    for _, item := range items {
        go func() { errCh <- validate(item) }()
    }

    var firstErr error
    for range items {
        if err := <-errCh; err != nil && firstErr == nil {
            firstErr = err
        }
    }
    return firstErr
}

The loop runs the full len(items) iterations even after finding an error. That is deliberate: it is what guarantees every goroutine’s send is consumed and every goroutine exits.

Collect all:

// Illustrative snippet — not a complete program
func validateForm(fields []Field) error {
    errCh := make(chan error, len(fields))

    for _, f := range fields {
        go func() { errCh <- validate(f) }()
    }

    var errs []error
    for range fields {
        if err := <-errCh; err != nil {
            errs = append(errs, err)
        }
    }
    return errors.Join(errs...) // nil when errs is empty
}

errors.Join (Go 1.20) combines the errors into one whose Error() joins the messages with newlines, and returns nil for an empty or all-nil slice — exactly the behaviour you want, with no length check.

14.2.4 The WaitGroup and Close Pattern

The counter loop requires every goroutine to send, including on success. Sometimes you want silence on success — long-running workers that report problems as they occur, where there is no fixed number of sends to count. Then the receiver needs a different termination signal, and that signal is close.

// Illustrative snippet — not a complete program
func processAll(items []Item) error {
    errCh := make(chan error, len(items))
    var wg sync.WaitGroup

    for _, item := range items {
        wg.Go(func() {
            if err := process(item); err != nil {
                errCh <- err // only on failure
            }
        })
    }

    go func() {
        wg.Wait()
        close(errCh) // after every possible send
    }()

    var errs []error
    for err := range errCh {
        errs = append(errs, err)
    }
    return errors.Join(errs...)
}

Why the closer runs in its own goroutine. The main goroutine has two jobs that cannot be sequenced: draining with for range (which ends only at close) and knowing when the senders are finished (wg.Wait). Putting wg.Wait first and then draining works with a full-size buffer, but it collects nothing until the last goroutine finishes, and it deadlocks if the buffer is smaller than the number of failures. Draining first never reaches wg.Wait at all. A third goroutine running wg.Wait concurrently with the drain resolves it: errors are handled as they arrive, and close fires exactly once every sender is done.

Not every error channel needs closing. With the counter loop of §14.2.3 the receiver already knows how many values are coming, and an unclosed channel with no references is simply collected. Close when you need for range semantics, and not otherwise.

14.2.5 Integrating with Context Cancellation

select composes an error channel with cancellation exactly as §4.2 composes anything else:

// Illustrative snippet — not a complete program
func chargeOrder(ctx context.Context, order Order) error {
    errCh := make(chan error, 1)

    go func() { errCh <- processPayment(ctx, order) }()

    select {
    case err := <-errCh:
        return err
    case <-ctx.Done():
        return ctx.Err()
    }
}

The buffer of one is what makes the ctx.Done() branch safe. Take that away and every cancellation leaks the payment goroutine.

For a batch, cancel on the first error so the rest stop early:

// Illustrative snippet — not a complete program
func fetchAll(ctx context.Context, urls []string) error {
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    errCh := make(chan error, len(urls))
    for _, u := range urls {
        go func() { errCh <- fetch(ctx, u) }()
    }

    var firstErr error
    for range urls {
        if err := <-errCh; err != nil && firstErr == nil {
            firstErr = err
            cancel() // the rest see ctx.Done() and return
        }
    }
    return firstErr
}

The caller still performs all len(urls) receives, but after cancel() the remaining goroutines return almost immediately with ctx.Err(). The function returns the real error, because firstErr was already set before any context error could arrive. cancel() does not kill anything — it asks, and fetch has to be listening. That is §13.4's cooperative cancellation, unchanged.

This is the entire pattern that errgroup.WithContext packages into one line (§14.4.3).

14.2.6 Where Error Channels Shine

errgroup is better than this for a bounded batch. What it cannot do is run forever. Long-lived workers that report errors continuously as they process a stream are the case where an error channel is the right primitive and nothing else is close:

// Illustrative snippet — not a complete program
func runWorkers(ctx context.Context, jobs <-chan Job) <-chan error {
    errCh := make(chan error, 10) // absorbs bursts
    var wg sync.WaitGroup

    for range 5 {
        wg.Go(func() {
            for {
                select {
                case <-ctx.Done():
                    return
                case job, ok := <-jobs:
                    if !ok {
                        return
                    }
                    err := job.Process()
                    if err == nil {
                        continue
                    }
                    wrapped := fmt.Errorf("job %s: %w", job.ID, err)
                    select {
                    case errCh <- wrapped:
                    case <-ctx.Done():
                        return
                    }
                }
            }
        })
    }

    go func() {
        wg.Wait()
        close(errCh)
    }()

    return errCh
}

There is no “result” here to return, and errgroup would return on the first error and stop the pool. The error channel is the only one of the three that streams.

14.2.7 Common Mistakes

Summary: Error Channels

An error channel is a chan error and the discipline that goes with it. The discipline is one rule stated twice: every goroutine sends exactly once on every path, and the buffer is large enough that no send can block.

Get the buffer wrong and you get one of two failures. Too small with a receiver that can leave early leaks a goroutine per abandoned send. Too small with a WaitGroup deadlocks, because the send blocks before Done can run while the main goroutine is inside Wait. Both disappear when the buffer matches the sender count, and the cost of that is 16 bytes and one allocation.

Two receive loops go with it. Count receives when every goroutine always sends — the count is the termination signal and nothing needs closing. Range over the channel when goroutines are silent on success, and then a separate goroutine must run wg.Wait and close concurrently with the drain, because the main goroutine cannot do both.

Where this pattern earns its place over errgroup is the unbounded case: long-lived workers reporting errors as they go. And there the buffer is a heuristic rather than a bound, so every send needs a select on ctx.Done() to stay cancellable when it fills.

Self-Check Questions: Error Channels

Why does this deadlock, and what is the smallest fix?

// Illustrative snippet — not a complete program
var wg sync.WaitGroup
errCh := make(chan error)

for range 5 {
    wg.Go(func() { errCh <- errors.New("failed") })
}

wg.Wait()
err := <-errCh

14.3 Result Structs

A chan error answers one question: did it work? The moment a goroutine produces something the caller wants, that channel is the wrong shape, and the obvious repair — a second channel for the values — is worse than the disease.

14.3.1 The Two-Channel Problem

// Illustrative snippet — not a complete program
// ✗ BAD: separate channels for values and errors
bodyCh := make(chan []byte, len(urls))
errCh := make(chan error, len(urls))

for _, url := range urls {
    go func() {
        body, err := fetch(url)
        if err != nil {
            errCh <- err
            return
        }
        bodyCh <- body
    }()
}

How many receives on each? You cannot know before running it — the split between successes and failures is the thing you are trying to discover. A select in a counted loop solves the arithmetic, and three problems survive it: which URL produced this body, which URL produced that error, and how to pair a value with the failure of the same operation. Splitting related facts across two channels discards the relationship between them.

// Illustrative snippet — not a complete program
type FetchResult struct {
    URL  string // identity: safe to read whatever Err says
    Body []byte // value: meaningless when Err is non-nil
    Err  error
}

One channel. One loop. Every value self-describing.

14.3.2 The Basic Pattern

// Illustrative snippet — not a complete program
func fetchAll(urls []string) []FetchResult {
    ch := make(chan FetchResult, len(urls))

    for _, url := range urls {
        go func() {
            body, err := fetch(url)
            ch <- FetchResult{URL: url, Body: body, Err: err}
        }()
    }

    results := make([]FetchResult, 0, len(urls))
    for range urls {
        results = append(results, <-ch)
    }
    return results
}

The rules are §14.2's rules with a richer payload: always send, buffer to the sender count, count the receives.

Check Err before Value. This is the whole contract, and it is the same discipline as sequential Go — you do not use result before checking err. It matters more here because the compiler will not help: an unused struct field is not an error, so reading r.Body when r.Err != nil compiles cleanly and silently produces garbage.

Err == nil  ─► Value is valid. Use it.

Err != nil  ─► Value is UNDEFINED. It may be
               the zero value, or half-written,
               or stale from a retry.

Identity    ─► always readable, either way.
               That is what it is for.

r := <-ch
if r.Err != nil { ... }   ← first
use(r.Value)              ← only then

Designing the struct. Three kinds of field, and the identity one is what fan-out is for: with ten goroutines finishing in an order nobody controls, a result without an identity cannot tell you which input failed.

// Illustrative snippet — not a complete program
type QueryResult struct {
    Query   string        // identity
    Rows    []Row         // value
    Elapsed time.Duration // value
    Err     error
}

14.3.3 Generic Result Types

When the struct is genuinely just a value and an error, generics remove the repetition:

// Illustrative snippet — not a complete program
type Result[T any] struct {
    Value T
    Err   error
}

A reusable helper follows, with one type parameter for the input and one for the output:

// Illustrative snippet — not a complete program
// RunAll runs fn for every item concurrently and collects the results
// in completion order. Use an indexed variant when order matters.
func RunAll[T, R any](items []T, fn func(T) (R, error)) []Result[R] {
    ch := make(chan Result[R], len(items))

    for _, item := range items {
        go func() {
            val, err := fn(item)
            ch <- Result[R]{Value: val, Err: err}
        }()
    }

    out := make([]Result[R], 0, len(items))
    for range items {
        out = append(out, <-ch)
    }
    return out
}

Each call needs its own variable, since the element types differ:

// Illustrative snippet — not a complete program
users := RunAll(userIDs, lookupUser)      // []Result[User]
receipts := RunAll(orders, validateOrder) // []Result[Receipt]

Use the generic form for library code and for the plain value-or-error case. Use a concrete struct the moment you need an identity field, a second value field, or a domain-meaningful type name — which in application code is most of the time. Start concrete and extract the generic version when the pattern actually repeats.

14.3.4 Collecting Results, Ordered and Not

Unordered collection is the loop you have already seen: receive len(items) times and append. Results arrive in completion order.

When results[i] must correspond to input[i], the simplest correct answer needs no channel at all:

// Illustrative snippet — not a complete program
func fetchAllOrdered(ctx context.Context,
    urls []string) ([]FetchResult, error) {
    results := make([]FetchResult, len(urls))
    var wg sync.WaitGroup

    for i, url := range urls {
        wg.Go(func() {
            body, err := httpGet(ctx, url)
            results[i] = FetchResult{URL: url, Body: body, Err: err}
        })
    }
    wg.Wait()

    var errs []error
    for _, r := range results {
        if r.Err != nil {
            errs = append(errs, fmt.Errorf("%s: %w", r.URL, r.Err))
        }
    }
    return results, errors.Join(errs...)
}

Two facts make this race-free, and both are needed. Each goroutine writes to a distinct index, so no two writes touch the same memory. And wg.Wait() establishes the happens-before edge (§8.4) between every write and the caller’s reads. Neither alone is sufficient: distinct indices without the barrier is still a race with the reader.

First success wins is the useful variant of the unordered loop:

// Illustrative snippet — not a complete program
func fetchFromMirrors(ctx context.Context,
    mirrors []string) ([]byte, error) {
    ctx, cancel := context.WithCancel(ctx)
    defer cancel() // stop the losers once we have an answer

    ch := make(chan FetchResult, len(mirrors))
    for _, m := range mirrors {
        go func() {
            body, err := httpGet(ctx, m)
            ch <- FetchResult{URL: m, Body: body, Err: err}
        }()
    }

    var lastErr error
    for range mirrors {
        r := <-ch
        if r.Err == nil {
            return r.Body, nil // defer cancel() releases the rest
        }
        lastErr = r.Err
    }
    return nil, fmt.Errorf("all %d mirrors failed: %w",
        len(mirrors), lastErr)
}

Returning early leaves goroutines running, and that is fine here: the buffer holds len(mirrors) values and each goroutine sends once, so no send can block. They finish, deposit, and exit; the channel is collected with values still in it.

14.3.5 Partial Results

Result structs are the only one of the three mechanisms that shows the caller everything — the successes, the failures, and which is which:

// Illustrative snippet — not a complete program
type HealthResult struct {
    Service string
    Latency time.Duration
    Err     error
}

func checkServices(ctx context.Context,
    services []string) ServiceReport {
    ch := make(chan HealthResult, len(services))
    for _, svc := range services {
        go func() {
            latency, err := ping(ctx, svc)
            ch <- HealthResult{Service: svc, Latency: latency, Err: err}
        }()
    }

    var report ServiceReport
    for range services {
        if r := <-ch; r.Err != nil {
            report.Failed = append(report.Failed, r)
        } else {
            report.Healthy = append(report.Healthy, r)
        }
    }
    return report
}

The caller then decides the policy, which is the whole point — §14.7 is about making that decision well. When aggregating errors, include the identity or the report is useless:

// Illustrative snippet — not a complete program
errs = append(errs, fmt.Errorf("%s: %w", r.Service, r.Err))
// cache: connection refused
// search: timeout after 5s

Partial results are the wrong answer when all results are required, when the results are interdependent, or when partial data is misleading rather than incomplete — an average over seven of ten values is not approximately right, it is wrong.

14.3.6 Cancel on First Error

When every goroutine must succeed, stop the rest as soon as one fails:

// Illustrative snippet — not a complete program
func fetchAllOrNothing(ctx context.Context,
    urls []string) ([]FetchResult, error) {
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    ch := make(chan FetchResult, len(urls))
    for _, url := range urls {
        go func() {
            body, err := httpGet(ctx, url)
            ch <- FetchResult{URL: url, Body: body, Err: err}
        }()
    }

    results := make([]FetchResult, 0, len(urls))
    for i := range urls {
        r := <-ch
        if r.Err != nil {
            cancel() // the rest return ctx.Err() shortly

            // Drain the outstanding sends before returning, so that
            // when this function returns, none of its goroutines are
            // still running. Nothing would block if we skipped this
            // -- the buffer holds every send -- but the goroutines
            // would outlive the call and be cleaned up whenever the
            // scheduler and GC got to them.
            for range len(urls) - i - 1 {
                <-ch
            }
            return nil, fmt.Errorf("fetch %s: %w", r.URL, r.Err)
        }
        results = append(results, r)
    }
    return results, nil
}

§14.4.3 replaces all of this — the derived context, the cancel, the drain — with errgroup.WithContext, which provides the same guarantee by construction.

14.3.7 Common Mistakes

Summary: Result Structs

A result struct is one channel carrying three things: an identity, a value, and an error. That bundling is what two channels cannot do — split a value from its error and you lose the fact that they describe the same operation, along with any way to say which input produced either. It is also cheaper, at 432 B against 512 B for four goroutines.

The contract is one line: when Err is nil the value is valid, when Err is non-nil the value is undefined, and the identity is readable either way. The compiler enforces none of this, which is why the discipline has to be explicit.

Order costs nothing if you want it. Writing to distinct indices of a pre-allocated slice and waiting on a WaitGroup is race-free — distinct writes plus the happens-before edge from Wait — and needs no channel at all. Use a channel when the consumer benefits from results as they arrive.

Returning early from a fully buffered result channel does not leak, because every send has a slot waiting. Draining anyway buys determinism about when the goroutines finish, which is a real guarantee and a different one from leak-freedom.

Self-Check Questions: Result Structs

What is wrong here?

// Illustrative snippet — not a complete program
r := <-results
fmt.Printf("fetched %d bytes from %s\n", len(r.Body), r.URL)
if r.Err != nil {
    log.Printf("error: %v", r.Err)
}

14.4 errgroup

Sections 14.2 and 14.3 built the return path from primitives, and that was the point — you now know what the buffer is for and what the drain buys. This section is the package that does it for you, and the reason to reach for it is not only that it is shorter.

14.4.1 The Boilerplate Problem

Validating a set of configuration files by hand needs a WaitGroup, a channel with a buffer decision, a closer goroutine and a drain loop:

// Illustrative snippet — not a complete program
// ✗ Manual, and subtly wrong
func validateConfigs(ctx context.Context, paths []string) error {
    var wg sync.WaitGroup
    errCh := make(chan error, len(paths))

    for _, path := range paths {
        wg.Go(func() { errCh <- validateConfig(ctx, path) })
    }

    go func() {
        wg.Wait()
        close(errCh)
    }()

    for err := range errCh {
        if err != nil {
            return err // ✗ returns while goroutines are still running
        }
    }
    return nil
}

The bug is the early return: the function exits with workers still in flight and the closer goroutine orphaned. Fixing it means draining every send first, which adds more ceremony to the thing that already had too much.

// Illustrative snippet — not a complete program
// ✓ errgroup
func validateConfigs(ctx context.Context, paths []string) error {
    g, ctx := errgroup.WithContext(ctx)

    for _, path := range paths {
        g.Go(func() error { return validateConfig(ctx, path) })
    }

    return g.Wait()
}

14.4.2 Basic Usage

The zero value works and needs no constructor:

// Illustrative snippet — not a complete program
func validateAll(items []Item) error {
    var g errgroup.Group

    for _, item := range items {
        g.Go(func() error { return validate(item) })
    }

    return g.Wait()
}

g.Wait() blocks until every goroutine launched by g.Go has returned, then gives you the first non-nil error — first in the temporal sense, whichever reached the group’s internal state first. Errors after that are discarded. That is a deliberate trade of completeness for simplicity, and §14.4.7 shows what to do when you need all of them.

The guarantee that Wait waits for all goroutines is the important one: there is no way to leak a goroutine through this API. In §14.2 you got that by draining N receives; here it is structural.

14.4.3 WithContext: Cancel on First Error

errgroup.WithContext returns a group and a derived context. When the first goroutine returns a non-nil error, that context is cancelled:

// Illustrative snippet — not a complete program
func fetchAll(ctx context.Context, urls []string) error {
    g, ctx := errgroup.WithContext(ctx)

    for _, url := range urls {
        g.Go(func() error { return httpGet(ctx, url) })
    }

    return g.Wait()
}

Shadowing the outer ctx is intentional. Give the derived context a different name and you leave a working ctx in scope that silently bypasses the cancellation:

// Illustrative snippet — not a complete program
// ✗ BAD: gCtx exists, but the goroutine uses the parent
g, gCtx := errgroup.WithContext(ctx)
g.Go(func() error { return httpGet(ctx, url) })

Shadow it unless you need the parent afterwards — cleanup after g.Wait() is the usual reason, since the derived context is always cancelled by then.

What g.Wait actually returns. It returns the first non-nil error any goroutine returned, and it does no filtering whatsoever. When a real failure landed first, that is your root cause. When the parent context was cancelled instead, every goroutine returns ctx.Err() and that is what you get:

Cancellation is still cooperative. errgroup cancels a context; it cannot stop a goroutine. A g.Go closure that never checks ctx and calls a function that does not take one will run to completion regardless.

14.4.4 Concurrency Limiting

g.SetLimit(n) caps the number of goroutines active in the group. Past the limit, g.Go blocks the caller until a slot frees:

// Illustrative snippet — not a complete program
g, ctx := errgroup.WithContext(ctx)
g.SetLimit(10)

for _, url := range urls {
    g.Go(func() error { return httpGet(ctx, url) }) // blocks at 10
}
return g.Wait()

That is the difference from the semaphore pattern it replaces. A semaphore inside the closure launches every goroutine immediately and has them queue:

// Illustrative snippet — not a complete program
// Before SetLimit: all N goroutines exist, 10 of them work
sem := make(chan struct{}, 10)
g.Go(func() error {
    sem <- struct{}{}
    defer func() { <-sem }()
    return httpGet(ctx, url)
})

SEMAPHORE INSIDE THE CLOSURE
  caller loop ──► 10,000 goroutines exist
                  10 run, 9,990 park on sem
                  25.6 MiB of parked goroutines

SetLimit(10)
  caller loop ──► blocks in g.Go at the limit
                  10 goroutines exist, all running
                  ~27 KiB

g.Go blocks the CALLER. The goroutine is not created
until there is room for it to run.

Rules worth knowing:

• Call SetLimit before the first g.Go, or after Wait. The real contract is that the limit must not change while goroutines are active.
• A negative limit means no limit, which is the default.
• SetLimit(0) makes a zero-capacity semaphore: Go blocks forever, TryGo always returns false. The documentation describes it as preventing any new goroutines from being added, which is a legitimate way to close a group to further work.
• The limit counts active goroutines. A finished goroutine frees its slot immediately.

TryGo is Go without the blocking — it returns false rather than waiting, which is what load shedding needs:

// Illustrative snippet — not a complete program
for req := range requests {
    if !g.TryGo(func() error { return processRequest(ctx, req) }) {
        req.Respond(http.StatusServiceUnavailable)
    }
}

Without a limit set, TryGo always succeeds, because there is no limit to reach.

Choosing the limit. Start at runtime.NumCPU() for CPU-bound work and roughly double that for I/O-bound, then measure. The real bound is usually a downstream resource: a connection pool size, a rate limit you were given, a file-descriptor ceiling, or total memory divided by per-item footprint.

14.4.5 The Return Value Decision

What the closure returns is the entire error strategy. There are three answers.

return err — fail fast. The first failure cancels the derived context and Wait reports it. Use when any single failure invalidates the batch.

return nil — collect all. No error reaches the group, nothing is cancelled, every goroutine runs to completion, and Wait returns nil. The failures live wherever you put them, usually a results slice. Use when partial results have value.

Conditional — selective. Only fatal errors propagate:

// Illustrative snippet — not a complete program
g.Go(func() error {
    val, err := process(ctx, order)
    results[i] = Result[Value]{Value: val, Err: err}

    if isInfrastructureError(err) {
        return err // database down: stop everything
    }
    return nil // one bad order: collect it and continue
})

14.4.6 Composing with Result Structs

errgroup returns errors, never values. Combining it with §14.3's indexed slice is the most common production shape in this chapter:

// Illustrative snippet — not a complete program
type Service struct {
    Name     string
    Critical bool
}

func (s Service) Ping(ctx context.Context) error { /* ... */ }

type ServiceStatus struct {
    Name    string
    Healthy bool
    Latency time.Duration
    Err     error
}

func checkHealth(ctx context.Context,
    services []Service) ([]ServiceStatus, error) {
    results := make([]ServiceStatus, len(services))
    g, ctx := errgroup.WithContext(ctx)
    g.SetLimit(5)

    for i, svc := range services {
        g.Go(func() error {
            start := time.Now()
            err := svc.Ping(ctx)
            results[i] = ServiceStatus{
                Name:    svc.Name,
                Healthy: err == nil,
                Latency: time.Since(start),
                Err:     err,
            }
            if svc.Critical && err != nil {
                return fmt.Errorf("critical service %s: %w",
                    svc.Name, err)
            }
            return nil
        })
    }

    if err := g.Wait(); err != nil {
        return results, err // partial results are still useful
    }
    return results, nil
}

The slice writes are safe for the same two reasons as §14.3.4: distinct indices, and the happens-before edge that g.Wait() provides. WithContext earns its place even though most closures return nil — if the parent is cancelled because the server is shutting down, every ping stops promptly.

14.4.7 Collecting All Errors

Wait gives you one error. Two ways to get the rest.

Store them in the results slice, which costs nothing extra if you already have one:

// Illustrative snippet — not a complete program
var errs []error
for _, r := range results {
    if r.Err != nil {
        errs = append(errs, fmt.Errorf("%s: %w", r.Name, r.Err))
    }
}
return errors.Join(errs...)

Use a mutex when the goroutines are side-effecting and have no natural index:

// Illustrative snippet — not a complete program
var (
    mu      sync.Mutex
    allErrs []error
)

for _, region := range regions {
    g.Go(func() error {
        if err := deploy(ctx, region, artifact); err != nil {
            mu.Lock()
            allErrs = append(allErrs, fmt.Errorf("%s: %w", region, err))
            mu.Unlock()
        }
        return nil // never cancel a sibling region
    })
}
g.Wait()

14.4.8 How errgroup Works

The package is about a hundred lines. The parts that matter:

// Illustrative snippet — not a complete program
type Group struct {
    cancel  func(error)     // from context.WithCancelCause
    wg      sync.WaitGroup
    sem     chan token      // nil unless SetLimit was called
    errOnce sync.Once
    err     error
}

func WithContext(ctx context.Context) (*Group, context.Context) {
    ctx, cancel := context.WithCancelCause(ctx)
    return &Group{cancel: cancel}, ctx
}

func (g *Group) Go(f func() error) {
    if g.sem != nil {
        g.sem <- token{} // blocks the caller at the limit
    }
    g.wg.Add(1)
    go func() {
        defer g.done()
        if err := f(); err != nil {
            g.errOnce.Do(func() {
                g.err = err
                if g.cancel != nil {
                    g.cancel(g.err)
                }
            })
        }
    }()
}

Everything in §14.2 and §14.3 is visible here: a WaitGroup for the lifecycle, a sync.Once for the first-error guard, a buffered channel as a semaphore. Wait calls g.wg.Wait() and then g.cancel(g.err) unconditionally, which is why the derived context is always done afterwards.

The detail worth carrying away is WithCancelCause. The cancel function takes an error, and errgroup passes it the failure that triggered the cancellation. So inside a sibling goroutine that has just noticed ctx.Done():

// Illustrative snippet — not a complete program
select {
case <-ctx.Done():
    // ctx.Err()          → context.Canceled     (says nothing)
    // context.Cause(ctx) → "db is down"         (the real reason)
    return ctx.Err()
}

14.4.9 Common Mistakes

Two of these deserve more than a row.

Reuse after Wait fails silently. The group’s sync.Once has already fired, so the second batch’s error never reaches g.err:

Changing the limit panics, but the guard is a race. SetLimit panics when len(g.sem) != 0 — when goroutines currently hold tokens:

Summary: errgroup

errgroup packages the WaitGroup, the error channel, the closer goroutine and the drain loop into Go and Wait. It is not only shorter — it allocates about 40% less than the pattern it replaces, 256 bytes against 448 at eight goroutines, and it removes an entire class of bug because Wait cannot return while a goroutine from the group is still running.

WithContext derives a context cancelled by the first error. Wait returns that error unfiltered, which means it returns context.Canceled when the parent was cancelled rather than a goroutine failing — the filtering everyone assumes is there is not.

SetLimit blocks the caller rather than the goroutine, so the goroutine is never created until there is room to run it. That is the difference between ten goroutines and ten thousand, which on this machine is 27 KiB against 25.6 MiB.

What the closure returns is the strategy: err for fail-fast, nil for collect-all, conditional for selective. And underneath it is all Chapter 12's primitives — a WaitGroup, a sync.Once, a buffered channel — plus Chapter 13's WithCancelCause, which is why context.Cause inside a group member tells you why the group is shutting down.

Self-Check Questions: errgroup

14.5 Pipeline Error Handling

Chapter 7 built pipelines and deferred one question to this chapter: what happens when a stage fails? The answer is different from §14.2 through §14.4 because pipeline stages are connected — one stage’s output is the next one’s input — and that changes both where an error can go and what has to happen to the stages that are not failing.

14.5.1 Why Pipelines Are Different

A parallel group is N independent goroutines reporting to one caller. Errors go straight back. A pipeline has three properties that group does not:

Errors have a direction. A failure in stage two either travels forward through stages three, four and five as data, or triggers a backward cancellation. Those are different designs, not different spellings of one design.

Cancellation flows the wrong way. When a late stage fails, the early stages have to stop producing. Nothing in the channel topology does that — channels carry data downstream, and closure only propagates downstream too.

There is data in flight. Values sit in inter-stage buffers and goroutines sit blocked on sends. All of it has to unwind or the pipeline leaks.

             error here
                 │
 Gen ──► Stage A ──► Stage B ──► Consumer

 FORWARD, as data
   Result{Err} rides the channels to the end
   every item still flows; consumer decides
   ─────────────────────────────────────────►

 BACKWARD, as a signal
   ctx cancelled; every stage stops
 ◄─────────────────────────────────────────

Which one you want is a property of the work, not of
the pipeline. A log processor skips a bad line. A
financial validator must not.

Three strategies follow: propagate errors as values, fail fast with errgroup, or classify per-error and do both.

14.5.2 Propagating Errors as Values

The first fallible stage changes its return type from <-chan T to <-chan Result[T]. That stage is the error boundary, and every stage downstream of it works in Result[T].

readLines        parse           validate        enrich
<-chan string ─► <-chan          <-chan          <-chan
                 Result[Record]  Result[Record]  Result[Record]
                      ▲
                 error boundary

Upstream of it, a plain channel. Downstream, every value
carries its own error or its own success, and the type
says so.

// Illustrative snippet — not a complete program
func parse(ctx context.Context,
    lines <-chan string) <-chan Result[Record] {
    out := make(chan Result[Record])
    go func() {
        defer close(out)
        for line := range lines {
            record, err := parseLine(line)
            select {
            case <-ctx.Done():
                return
            case out <- Result[Record]{Value: record, Err: err}:
            }
        }
    }()
    return out
}

Two things: the stage always sends, success or failure, so nothing is lost; and the stage makes no policy decision about whether a parse error should stop anything. That is the consumer’s call.

The pass-through rule. A stage receiving a Result with a non-nil Err forwards it unchanged and never inspects Value:

// Illustrative snippet — not a complete program
func validate(ctx context.Context,
    in <-chan Result[Record]) <-chan Result[Record] {
    out := make(chan Result[Record])
    go func() {
        defer close(out)
        for r := range in {
            if r.Err != nil {
                select { // pass through untouched
                case <-ctx.Done():
                    return
                case out <- r:
                }
                continue
            }
            err := validateRecord(r.Value)
            select {
            case <-ctx.Done():
                return
            case out <- Result[Record]{Value: r.Value, Err: err}:
            }
        }
    }()
    return out
}

A stage has three options on receiving an error, and only two of them are ever right: forward it unchanged, or wrap it with this stage’s context (fmt.Errorf("at enrichment: %w", r.Err)) and forward that. Dropping it with a bare continue is §14.1's silent failure rebuilt inside a pipeline.

Assembly is then identical to a pipeline with no errors in it, which is the point:

// Illustrative snippet — not a complete program
func processLogs(ctx context.Context, filename string) error {
    lines, genErrCh := readLines(ctx, filename) // see §14.5.6
    parsed := parse(ctx, lines)
    validated := validate(ctx, parsed)
    enriched := enrich(ctx, validated)

    var errs []error
    var stored int
    for r := range enriched {
        if r.Err != nil {
            errs = append(errs, r.Err)
            continue
        }
        if err := store(r.Value); err != nil {
            errs = append(errs, fmt.Errorf("store: %w", err))
            continue
        }
        stored++
    }

    if err := <-genErrCh; err != nil { // the generator's own failure
        return fmt.Errorf("read %s: %w", filename, err)
    }

    slog.Info("processing complete",
        "stored", stored, "errors", len(errs))
    if len(errs) > 0 {
        return fmt.Errorf("%d records failed (first: %w)",
            len(errs), errs[0])
    }
    return nil
}

14.5.3 Fail-Fast with errgroup

When partial results are useless — a migration, a transaction, a configuration load — the first error should stop everything. Make each stage a member of one group:

// Illustrative snippet — not a complete program
func processFiles(ctx context.Context, dir string) error {
    g, ctx := errgroup.WithContext(ctx)

    paths := make(chan string)
    contents := make(chan FileData)

    g.Go(func() error { // stage 1: list
        defer close(paths)
        entries, err := os.ReadDir(dir)
        if err != nil {
            return fmt.Errorf("list: %w", err)
        }
        for _, e := range entries {
            if e.IsDir() {
                continue
            }
            select {
            case <-ctx.Done():
                return ctx.Err()
            case paths <- filepath.Join(dir, e.Name()):
            }
        }
        return nil
    })

    g.Go(func() error { // stage 2: read and parse
        defer close(contents)
        for path := range paths {
            data, err := readAndParse(path)
            if err != nil {
                return fmt.Errorf("parse %s: %w",
                    filepath.Base(path), err)
            }
            select {
            case <-ctx.Done():
                return ctx.Err()
            case contents <- data:
            }
        }
        return nil
    })

    g.Go(func() error { // stage 3: consume
        for data := range contents {
            if err := writeOutput(ctx, data); err != nil {
                return fmt.Errorf("write: %w", err)
            }
        }
        return nil
    })

    return g.Wait()
}

The shutdown cascade. Two mechanisms unwind the pipeline, and neither is sufficient alone:

 ctx cancellation flows UPSTREAM
 ◄──────────────────────────────
 Stage 1 ──► Stage 2 ──► Stage 3
                ✗
 ──────────────────────────────►
 channel closure flows DOWNSTREAM

A stage blocked SENDING is freed by ctx.Done().
A stage blocked RECEIVING is freed by close().

Stage 2 fails ─► errgroup cancels ctx
               ─► stage 1 unblocks from its send,
                  returns, and its defer closes paths
               ─► stage 2's defer closes contents
               ─► stage 3's for-range ends
               ─► g.Wait() returns stage 2's error

Every stage therefore needs three things: defer close(out) so downstream can end, a select on ctx.Done() around every send so it can be freed when downstream stops reading, and return ctx.Err() so the goroutine actually exits. The last stage has no output channel and so no defer close; if it does slow work, pass ctx into that work.

14.5.4 Classifying Errors Within Stages

Real pipelines are rarely all-or-nothing. A scraper should skip a 404 and abort on a DNS failure. An importer should skip a malformed row and abort when the database connection drops. The rule that separates them: an error is fatal if it affects every remaining item, and recoverable if it affects only this one.

// Illustrative snippet — not a complete program
type Severity int

const (
    Skip  Severity = iota // log it, keep going
    Fatal                 // cancel the pipeline
)

func classifyFetchError(err error) Severity {
    var dnsErr *net.DNSError
    if errors.As(err, &dnsErr) {
        return Fatal // the whole domain is unreachable
    }

    var httpErr *HTTPError
    if errors.As(err, &httpErr) {
        switch {
        case httpErr.StatusCode == 404, httpErr.StatusCode == 429:
            return Skip
        case httpErr.StatusCode >= 500:
            return Fatal
        }
    }

    if errors.Is(err, context.DeadlineExceeded) {
        return Skip // one slow item, not a broken pipeline
    }

    return Fatal // unknown errors are fatal by default
}

Go 1.26’s errors.AsType[*net.DNSError](err) and errors.AsType[*HTTPError](err) return (value, ok) and remove the two declarations; either form is fine.

Inside a g.Go closure the classification picks the return value — which is §14.4.5's decision, applied per error rather than per goroutine:

// Illustrative snippet — not a complete program
g.Go(func() error {
    defer close(fetched)
    for url := range urls {
        page, err := httpGet(ctx, url)
        if err != nil {
            wrapped := fmt.Errorf("fetch %s: %w", url, err)
            if classifyFetchError(err) == Fatal {
                return wrapped
            }
            select { // recoverable: send it on as a value
            case <-ctx.Done():
                return ctx.Err()
            case fetched <- Result[Page]{Err: wrapped}:
            }
            continue
        }
        select {
        case <-ctx.Done():
            return ctx.Err()
        case fetched <- Result[Page]{Value: page}:
        }
    }
    return nil
})

One stage, both strategies. That hybrid is what makes classification worth the complexity.

14.5.5 Fan-Out Stages

When one stage is the bottleneck, run N workers on it. The complication is that no single worker can close the shared output channel — closing while a sibling is still sending panics.

// Illustrative snippet — not a complete program
func parallelFetch(ctx context.Context,
    urls <-chan string) <-chan Result[Page] {
    out := make(chan Result[Page])

    go func() {
        defer close(out) // runs after g.Wait() below
        g, ctx := errgroup.WithContext(ctx)
        g.SetLimit(10)

        for url := range urls {
            g.Go(func() error {
                page, err := httpGet(ctx, url)
                select {
                case <-ctx.Done():
                    return ctx.Err()
                case out <- Result[Page]{Value: page, Err: err}:
                }
                return nil // errors travel as values, not through Wait
            })
        }
        _ = g.Wait()
    }()

    return out
}

The outer goroutine owns the channel and drives the group, so from the outside this stage looks like any other. defer close(out) runs after g.Wait() returns, which is what guarantees every send has finished before the close.

For a fan-out inside a pipeline-wide group, a WaitGroup tracks the workers and a closer goroutine handles the channel:

// Illustrative snippet — not a complete program
var wg sync.WaitGroup
for range workers {
    wg.Add(1)
    g.Go(func() error {
        defer wg.Done()
        for raw := range rawCh {
            record, err := transformRecord(raw)
            if err != nil {
                return fmt.Errorf("transform: %w", err)
            }
            select {
            case <-ctx.Done():
                return ctx.Err()
            case recordCh <- record:
            }
        }
        return nil
    })
}

go func() {
    wg.Wait()
    close(recordCh)
}()

Two coordination mechanisms because they do different jobs: errgroup owns errors and cancellation across all stages, but it does not know which goroutines own which channel and so cannot close recordCh. The WaitGroup tracks exactly the workers that send on it.

When one worker fails: it returns an error, errgroup cancels ctx, and the siblings exit — but by two different routes, and the distinction matters. A worker blocked on recordCh <- record is freed by ctx.Done() in its select. A worker blocked on for raw := range rawCh is not — a receive does not watch the context. It exits only when the upstream stage closes rawCh, which happens because that stage was itself freed by the cancellation. Both routes end at wg.Done(), then close(recordCh), then the downstream for range ends.

14.5.6 Generator Errors

A generator produces the first channel, so it has nowhere upstream to send an error and no Result channel yet to put one in. The failure mode is silence:

// Illustrative snippet — not a complete program
const selectRecords = "SELECT id, data FROM records"

// ✗ BROKEN: consumer cannot tell "no records" from "query failed"
func readRecords(ctx context.Context, db *sql.DB) <-chan Record {
    out := make(chan Record)
    go func() {
        defer close(out)
        rows, err := db.QueryContext(ctx, selectRecords)
        if err != nil {
            return // error lost; channel just closes
        }
        defer rows.Close()
        // ... scan and send ...
    }()
    return out
}

Two fixes, and which one is right follows from the pipeline’s strategy.

Return a second channel when a generator failure is always fatal:

// Illustrative snippet — not a complete program
func readRecords(ctx context.Context,
    db *sql.DB) (<-chan Record, <-chan error) {
    out := make(chan Record)
    errCh := make(chan error, 1) // buffered: may never be read

    go func() {
        defer close(out)
        defer close(errCh)

        rows, err := db.QueryContext(ctx, selectRecords)
        if err != nil {
            errCh <- fmt.Errorf("query: %w", err)
            return
        }
        defer rows.Close()

        for rows.Next() {
            var r Record
            if err := rows.Scan(&r.ID, &r.Data); err != nil {
                errCh <- fmt.Errorf("scan: %w", err)
                return
            }
            select {
            case <-ctx.Done():
                return
            case out <- r:
            }
        }
        if err := rows.Err(); err != nil {
            errCh <- fmt.Errorf("rows: %w", err)
        }
    }()

    return out, errCh
}

The consumer checks <-errCh after the data channel is exhausted, as processLogs does in §14.5.2. Closing errCh is what makes that receive safe when nothing failed — it yields the zero value, nil.

Emit Result values when the pipeline is collect-all and a bad row is just another item to report. Then a scan error becomes Result[Record]{Err: ...} followed by continue, and the generator keeps reading. The difference between the two versions is exactly the difference between return and continue, which is the strategy made concrete.

14.5.7 Common Mistakes

The last one is worth expanding. When errgroup cancels the context, ctx.Err() is context.Canceled — the symptom, never the cause:

// Illustrative snippet — not a complete program
err := g.Wait()

// ✗ loses the actual failure
if ctx.Err() != nil {
    log.Fatal(ctx.Err()) // "context canceled"
}

// ✓ the root cause, with stage identity
if err != nil {
    log.Fatal(err) // "transform: field 'amount': invalid syntax"
}

And inside a stage that is shutting down and has no access to g.Wait(), context.Cause(ctx) gives the same root cause (§14.4.8) — which is how a stage logs why it is stopping while it stops.

Summary: Pipeline Error Handling

Pipelines differ from parallel groups in one structural way: the stages are connected, so an error either travels forward as data or backward as a cancellation, and the stages that did not fail have to unwind either way.

Propagating errors as values makes the first fallible stage an error boundary, converting <-chan T to <-chan Result[T]. Everything downstream forwards errors untouched. The pipeline assembles exactly as it would with no errors in it, and the price is the pass-through check in every stage.

Fail-fast makes each stage a member of one errgroup. Unwinding needs both mechanisms: context cancellation frees stages blocked on a send, channel closure frees stages blocked on a receive. Miss the select on a send and the stage hangs instead of failing.

Classification is the hybrid, and the rule that decides it is whether the error affects every remaining item or only this one. Unknown errors default to fatal, because stopping on something you do not understand is recoverable and silently skipping it is not.

Self-Check Questions: Pipeline Error Handling

Find the bugs.

// Illustrative snippet — not a complete program
g, ctx := errgroup.WithContext(context.Background())
dataCh := make(chan Data)

g.Go(func() error {
    defer close(dataCh)
    for _, url := range urls {
        data, err := download(url)
        if err != nil {
            return err
        }
        dataCh <- data
    }
    return nil
})

14.6 Panics in Goroutines

Everything so far has been about errors — failures the code anticipated. A panic is the other kind: a nil dereference, an index out of range, a failed type assertion, a library that gave up. In sequential code one recover at the top of the stack contains all of them. In concurrent code that containment does not exist, and the consequence is not a lost error but a dead process.

14.6.1 Why Panics Are Different Here

recover works on one call stack. go creates a new one. A deferred recover in the parent runs on the parent’s stack and will never see a child’s panic:

SEQUENTIAL — one stack, one recovery point
  main()  ◄── defer/recover here catches everything below
    ├── processA()
    │     └── helper()     panic caught by main
    └── processB()
          └── parse()      panic caught by main

CONCURRENT — separate stacks, no inheritance
  main()  ◄── defer/recover here catches nothing below
    ├── go processA()      needs its own recover
    │     └── helper()     otherwise: process dies
    └── go processB()      needs its own recover
          └── parse()      otherwise: process dies

Spawn a hundred goroutines and you need a hundred recovery points. Miss one and a panic in that one goroutine terminates the process, taking the ninety-nine that were working fine with it.

Recovering is not the same as being fine. The panic still interrupted whatever the goroutine had promised to do:

What can panic, and what is beyond reach. Ordinary recoverable panics: nil pointer dereference, index out of range, failed type assertion, send on a closed channel, closing a closed or nil channel, a negative WaitGroup counter, an explicit panic() in a library. Writing to a nil map is also an ordinary panic and recover catches it normally.

These are not panics at all, and no defer runs for any of them:

The nil-map/concurrent-map pair is the one readers most often confuse: m[k] = v on a nil map is recoverable; the same statement racing another goroutine’s write is not. Prevention is the only defence for the second — a mutex, or sync.Map.

14.6.2 Converting Panics to Errors

Four parts, and leaving out any one of them breaks it:

// Illustrative snippet — not a complete program
func safeDo(fn func()) (err error) { // ① named return
    defer func() {                    // ② deferred function
        if r := recover(); r != nil { // ③ recover, called directly
            err = fmt.Errorf("panic: %v\n\n%s", r, debug.Stack()) // ④
        }
    }()
    fn()
    return nil
}

The named return is the part everyone forgets. Without it the deferred function has nothing to assign to, the function returns the zero value, and the caller is told everything succeeded.

recover must be called directly by the deferred function. A helper called by the deferred function gets nil — the specification says directly, and it means it.

The panic value can be any type. %v handles all of them; when it is already an error, %w preserves the chain for errors.Is and errors.As.

Capture the stack. debug.Stack() in the recovery defer includes the original panic site, which is worth stating plainly because it is widely doubted:

14.6.3 Recovery Wrappers

The boilerplate is identical every time, so wrap it once.

For errgroup:

// Illustrative snippet — not a complete program
func WithRecovery(fn func() error) func() error {
    return func() (err error) {
        defer func() {
            if r := recover(); r != nil {
                err = fmt.Errorf("panic: %v\n\n%s", r, debug.Stack())
            }
        }()
        return fn()
    }
}

g.Go(WithRecovery(func() error { return riskyOperation(ctx) }))

The group sees a recovered panic as an ordinary error: it cancels the context and g.Wait returns it.

For result channels, where a missing send deadlocks the receiver, put the send inside the defer so it happens on every exit path:

// Illustrative snippet — not a complete program
// ch MUST be buffered to at least the number of SafeGo calls: this
// send happens even when the receiver has given up, and an unbuffered
// channel would park the goroutine here forever (§14.2.2).
func SafeGo[T any](ch chan<- Result[T], fn func() (T, error)) {
    go func() {
        var result Result[T]
        defer func() {
            if r := recover(); r != nil {
                result.Err = fmt.Errorf("panic: %v\n\n%s",
                    r, debug.Stack())
            }
            ch <- result // every path sends exactly once
        }()
        result.Value, result.Err = fn()
    }()
}

For fire-and-forget goroutines, recovery means logging and continuing — appropriate for cache warming, metrics, non-critical cleanup:

// Illustrative snippet — not a complete program
func GoSafe(fn func()) {
    go func() {
        defer func() {
            if r := recover(); r != nil {
                slog.Error("goroutine panic",
                    "panic", r, "stack", string(debug.Stack()))
            }
        }()
        fn()
    }()
}

14.6.4 When to Recover and When to Crash

Recover at boundaries. Crash on invariants.

A boundary is where your code meets input you do not control: an HTTP handler, a worker consuming a queue, a pipeline stage reading a file, a call into a plugin. A panic there usually means “this input hit a path we did not handle”, and recovering is safe because the goroutine’s state is local to that one item, its siblings are working on different items, and the failure is attributable to something you can log and skip.

An invariant is an assumption your own code relies on — a pointer the constructor guaranteed non-nil, an index you already bounds-checked, a channel your protocol says is still open. A panic there means you have a bug, and recovering is dangerous: the bug may have corrupted state other goroutines depend on, continuing can turn a crash into wrong results or data loss, and the root cause goes unfixed because nothing surfaced.

RECOVER                      CRASH
──────────────────────       ──────────────────────
HTTP request handlers        Internal logic bugs
Worker pool jobs             Invariant violations
Pipeline stages              Corrupted shared state
Third-party / plugin code    Configuration errors
Untrusted input              Missing critical resources

because: state is local,     because: the bug must be
siblings are unaffected,     found, continuing is
the service stays up         unsafe, the crash is the
                             clearest possible signal

LITMUS TEST
After recovering, is the program's state still
trustworthy?   yes ─► recover    no ─► crash

The standard library follows this exactly. net/http recovers a panic in a handler, logs the stack, and closes that connection — other requests are untouched. It does not recover in ListenAndServe; a listener failure is infrastructure and should stop the process. Recover at request boundaries, crash at infrastructure boundaries.

Selective recovery lets you take the expected panics and re-raise the rest:

// Illustrative snippet — not a complete program
defer func() {
    if r := recover(); r != nil {
        if _, ok := r.(runtime.Error); ok {
            err = fmt.Errorf("transform panic: %v\n\n%s",
                r, debug.Stack())
            return
        }
        panic(r) // an explicit panic() means an assertion failed
    }
}()

Recover, log, re-panic when the process should still die but you want structured logging or a metric first:

// Illustrative snippet — not a complete program
defer func() {
    if r := recover(); r != nil {
        slog.Error("fatal panic",
            "panic", r, "stack", string(debug.Stack()))
        metrics.PanicTotal.Inc()
        panic(r)
    }
}()

Put recovery at the unit of work, not around a batch of unrelated calls:

// Illustrative snippet — not a complete program
func worker(jobs <-chan Order) {
    for order := range jobs {
        if err := safeProcess(order); err != nil {
            slog.Error("order failed", "order_id", order.ID, "err", err)
        }
    }
}

func safeProcess(order Order) (err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("panic processing order %s: %v\n\n%s",
                order.ID, r, debug.Stack())
        }
    }()
    return processOrder(order)
}

One panic affects one order. The worker logs it with the order ID and continues to the next.

14.6.5 Recovery and Resource Cleanup

Deferred functions still run during a panic — that is guaranteed. The subtlety is that some cleanup exposes broken state rather than tidying it.

defer mu.Unlock() prevents the deadlock, and hands the next goroutine whatever the panic left behind. When the protected data spans more than one statement, that is a real hazard:

// Illustrative snippet — not a complete program
type Store struct {
    mu    sync.Mutex
    data  map[string]Record
    index []string // must contain exactly the keys in data
}

func (s *Store) SafeUpdate(key string, rec Record) (err error) {
    s.mu.Lock()
    defer s.mu.Unlock() // ① registered first, so runs LAST

    defer func() { // ② registered second, so runs FIRST
        if r := recover(); r != nil {
            delete(s.data, key) // undo the write that did land
            err = fmt.Errorf("update panic: %v\n\n%s", r, debug.Stack())
        }
    }()

    s.data[key] = rec               // lands
    s.index = append(s.index, derive(rec)) // may panic: now
                                           // they disagree
    return nil
}

The two invariants — data and index holding the same keys — are broken between those two statements, which is exactly the window a panic can land in. LIFO ordering is what makes the repair possible: register the recovery defer after the unlock defer so it runs before it, and the state is consistent again by the time the lock is released.

The same LIFO rule applies to a pipeline stage: register defer close(out) first and the recovery defer second, so recovery captures the error before the close signals downstream.

Cleanup that only releases is always safe during a panic — close(ch), wg.Done(), file.Close(), tx.Rollback(), conn.Close(). They run in LIFO order while the panic is still propagating, work normally because they do not call recover, and the recovery defer registered outermost runs last and stops the unwinding.

14.6.6 Common Mistakes

The loop one is worth seeing, because it looks right:

// Illustrative snippet — not a complete program
// ✗ WRONG: one defer per iteration, none run until worker returns
for job := range jobs {
    defer func() {
        if r := recover(); r != nil {
            results <- Result{Err: fmt.Errorf("panic: %v", r)}
        }
    }()
    results <- Result{Value: process(job)}
}

With ten thousand jobs that is ten thousand stacked deferred functions, none of which runs until worker itself returns — and if job 5 panics, worker returns then, so jobs 6 onwards never run. Extracting the body into a safeProcess helper gives each job its own function scope and its own defer.

Summary: Panics in Goroutines

recover works on one stack and go makes a new one, so recovery does not cross a goroutine boundary. Every goroutine that might panic needs its own, and the one you miss takes the whole process down.

Converting a panic to an error needs four things together: a named return so the defer has somewhere to assign, a deferred function, recover called directly by it, and debug.Stack() for the location. The named return is the one that gets forgotten, and its absence turns a caught panic into a silent success.

The cost is not a factor. A recovery wrapper is about 1.3 ns over a bare defer and allocates nothing; an actual panic is around 240 ns. So whether to recover is decided entirely by whether the program’s state is still trustworthy afterwards.

Recover at boundaries — handlers, worker loops, stage entry points, third-party calls — where state is local and the failure is attributable. Crash on invariant violations, where the panic means your own assumption was wrong and continuing risks corrupt data. net/http draws the line in exactly this place, and some conditions are past reach entirely: a concurrent map access calls fatal() and no defer runs at all.

Self-Check Questions: Panics in Goroutines

14.7 Partial Failure and Degraded Operation

Sections 14.2 through 14.6 built the mechanisms. This section is about the decision they hand you: some goroutines succeeded and some failed — now what?

14.7.1 The Partial Failure Problem

Sequential failure is binary. Each step depends on the last, so an error means the remaining steps cannot run and there is nothing to decide.

Concurrent failure is a count. Five fan-out fetches return three successes and two failures, and the three successes do not depend on the two failures in any way. Discarding them throws away completed work; using them without saying they are incomplete produces confident wrong answers.

Returning both results and an error. Partial failure needs a function to return useful data and a non-nil error, which breaks Go’s usual convention that a non-nil error makes the other returns meaningless. That is fine as long as you say so:

// Illustrative snippet — not a complete program
// fetchAll fetches every URL concurrently.
//
// Both return values may be non-nil: results holds an entry for each
// URL in input order, and error describes the subset that failed. A
// nil error means every fetch succeeded. Callers that require
// completeness must check the error before using results.
func fetchAll(ctx context.Context,
    urls []string) ([]FetchResult, error) {
    results := make([]FetchResult, len(urls))
    var g errgroup.Group

    for i, url := range urls {
        g.Go(func() error {
            body, err := httpGet(ctx, url)
            results[i] = FetchResult{URL: url, Body: body, Err: err}
            return nil // never cancel a sibling
        })
    }
    g.Wait()

    var errs []error
    for _, r := range results {
        if r.Err != nil {
            errs = append(errs, fmt.Errorf("%s: %w", r.URL, r.Err))
        }
    }
    return results, errors.Join(errs...) // nil when nothing failed
}

Without that doc comment, callers apply the standard convention, see a non-nil error, and discard results they could have used.

14.7.2 Critical vs Optional

Not all concurrent work matters equally. The test is one question: can the caller do anything useful without this result?

The classification is a domain decision, not a code pattern, and it moves with context: reviews are optional on a product page and critical on a reviews page.

The implementation is §14.4.5's selective return, applied per goroutine:

// Illustrative snippet — not a complete program
func fetchProductPage(ctx context.Context,
    id string) (*PageResponse, error) {
    var (
        product Product
        price   PriceInfo
        reviews []Review
        recs    []Product
    )
    var (
        mu      sync.Mutex
        missing []string
    )
    recordMissing := func(name string, err error) {
        mu.Lock()
        missing = append(missing, name)
        mu.Unlock()
        slog.Warn("optional fetch failed",
            "component", name, "err", err)
    }

    g, ctx := errgroup.WithContext(ctx)

    g.Go(func() error { // CRITICAL
        var err error
        product, err = catalog.Get(ctx, id)
        if err != nil {
            return fmt.Errorf("product catalog: %w", err)
        }
        return nil
    })

    g.Go(func() error { // CRITICAL
        var err error
        price, err = pricing.Get(ctx, id)
        if err != nil {
            return fmt.Errorf("pricing: %w", err)
        }
        return nil
    })

    g.Go(func() error { // OPTIONAL
        var err error
        if reviews, err = reviewSvc.List(ctx, id); err != nil {
            recordMissing("reviews", err)
        }
        return nil // never propagate
    })

    g.Go(func() error { // OPTIONAL
        var err error
        if recs, err = recSvc.ForProduct(ctx, id); err != nil {
            recordMissing("recommendations", err)
        }
        return nil
    })

    if err := g.Wait(); err != nil {
        return nil, err // a critical fetch failed
    }

    quality := Full
    if len(missing) > 0 {
        quality = Degraded
    }
    return &PageResponse{
        Data:    PageData{Product: product, Price: price,
                           Reviews: reviews, Recommendations: recs},
        Quality: quality,
        Missing: missing,
    }, nil
}

Each goroutine writes its own variable, so the data needs no synchronisation — g.Wait() supplies the happens-before edge. The shared missing slice does need the mutex, because several goroutines can append to it.

When to use two groups instead. One group launches everything at once, which is what you want when the work is independent. Use two sequential groups when the optional work depends on the critical results — personalised recommendations that need the product’s category, for instance. Two phases cost you latency, since the optional work cannot start until the critical work finishes; they buy you the dependency ordering and make the two policies structurally obvious rather than encoded in return values.

// Illustrative snippet — not a complete program
// Phase 1: critical, fail-fast.
required, reqCtx := errgroup.WithContext(ctx)
required.Go(func() error { return loadCatalog(reqCtx) })
required.Go(func() error { return loadPricing(reqCtx) })
if err := required.Wait(); err != nil {
    return nil, err
}

// Phase 2: optional, collect-all, on a tighter budget of its own.
optCtx, cancel := context.WithTimeout(ctx, 150*time.Millisecond)
defer cancel()
var optional errgroup.Group
optional.Go(func() error { loadReviews(optCtx); return nil })
optional.Go(func() error { loadRecs(optCtx); return nil })
optional.Wait()

14.7.3 Threshold Policies

When goroutines all do the same work against different sources, importance is not per goroutine — it is a count. You need enough, not all.

// Illustrative snippet — not a complete program
// queryWithQuorum queries every replica and returns as soon as
// minRequired have succeeded.
//
// Both return values may be non-nil: the returned slice holds every
// success collected so far, and a non-nil error means the quorum was
// not reached. Callers that require the quorum must check the error.
func queryWithQuorum(
    ctx context.Context,
    replicas []string,
    query string,
    minRequired int,
) ([]QueryResult, error) {
    ctx, cancel := context.WithCancel(ctx)
    defer cancel() // release the losers on every return path

    ch := make(chan QueryResult, len(replicas)) // every send has a slot

    for _, addr := range replicas {
        go func() {
            data, err := queryReplica(ctx, addr, query)
            ch <- QueryResult{Replica: addr, Data: data, Err: err}
        }()
    }

    var successes []QueryResult
    failures := 0
    maxFailures := len(replicas) - minRequired

    for range replicas {
        r := <-ch
        if r.Err != nil {
            failures++
            if failures > maxFailures {
                return successes, fmt.Errorf(
                    "quorum failed: need %d, have %d, %d failed",
                    minRequired, len(successes), failures)
            }
            continue
        }
        successes = append(successes, r)
        if len(successes) >= minRequired {
            return successes, nil // enough; stop waiting
        }
    }
    return successes, nil
}

Two early exits, and both matter. Enough successes means stop waiting for slower replicas. Too many failures means the quorum is now arithmetically unreachable, so waiting for the rest cannot change the outcome.

Returning early leaves goroutines running, and the buffer at len(replicas) is what makes that safe — every send has a slot, so nobody blocks (§14.3.4). defer cancel() shortens their lifetime, which matters when they hold database connections.

Classification (§14.7.2) is for goroutines doing different kinds of work; thresholds are for goroutines doing the same work against different sources. They compose.

14.7.4 Time-Bounded Partial Results

Sometimes the bound is a deadline rather than a count: return whatever arrived when time runs out.

// Illustrative snippet — not a complete program
func searchWithDeadline(ctx context.Context, query string,
    backends []string) *SearchResponse {

    ctx, cancel := context.WithTimeout(ctx, 200*time.Millisecond)
    defer cancel()

    ch := make(chan BackendResult, len(backends))
    for _, name := range backends {
        go func() {
            hits, err := search(ctx, name, query)
            ch <- BackendResult{Backend: name, Hits: hits, Err: err}
        }()
    }

    var results []BackendResult
    for range backends {
        select {
        case r := <-ch:
            if r.Err != nil {
                slog.Warn("backend failed",
                    "backend", r.Backend, "err", r.Err)
                degradedBackends.Inc()
                continue
            }
            results = append(results, r)
        case <-ctx.Done():
            return buildResponse(results, len(backends)) // deadline hit
        }
    }
    return buildResponse(results, len(backends))
}

errgroup cannot do this. g.Wait() blocks until every goroutine returns, so there is no way to say “give me what you have after 200 ms” — you would get the results only after every goroutine noticed the cancellation and returned. The channel-and-select loop reads each result as it lands, which is what makes an early return possible.

Combining a deadline with a threshold gives the most robust policy — wait up to the deadline, then fail if what arrived is too thin:

// Illustrative snippet — not a complete program
var results []BackendResult
collect:
for range backends {
    select {
    case r := <-ch:
        if r.Err == nil {
            results = append(results, r)
        }
    case <-ctx.Done():
        // A bare "break" here would leave the select, not the loop.
        // The label is what exits the for. This is a common Go bug.
        break collect
    }
}

if len(results) < minResults {
    return nil, fmt.Errorf(
        "insufficient results: got %d, need %d (deadline %v)",
        len(results), minResults, deadline)
}

14.7.5 Fallback Strategies

A fallback converts a failure into a degradation. Tiers should run from highest quality to highest reliability:

// Illustrative snippet — not a complete program
func getRecommendations(ctx context.Context, userID string) []Product {
    if recs, err := mlEngine.Recommend(ctx, userID); err == nil {
        return recs
    } else {
        slog.Warn("ML recs failed", "user", userID, "err", err)
    }

    if recs, err := popularity.ByCategory(ctx, userID); err == nil {
        return recs
    } else {
        slog.Warn("popularity recs failed", "user", userID, "err", err)
    }

    if recs, err := cache.Get(ctx, "trending"); err == nil {
        return recs
    } else {
        slog.Warn("trending cache failed", "user", userID, "err", err)
    }

    return nil // graceful absence: render the page without the section
}

Each tier is simpler, faster and more reliable than the one above it. The last tier is often graceful absence — return nothing and let the caller render a placeholder. That is the simplest fallback and frequently the right one; build more tiers only when the feature’s absence genuinely hurts.

Racing a fallback cuts latency when the primary is slow rather than broken — but only if you are honest about what it costs:

// Illustrative snippet — not a complete program
func getPrice(ctx context.Context, id string) (PriceInfo, error) {
    ctx, cancel := context.WithTimeout(ctx, 100*time.Millisecond)
    defer cancel()

    type attempt struct {
        price PriceInfo
        err   error
        tier  string
    }
    ch := make(chan attempt, 2)

    go func() {
        p, err := pricingSvc.Get(ctx, id)
        ch <- attempt{p, err, "realtime"}
    }()

    go func() {
        // Deliberately delayed: the cache is almost always faster, so
        // starting both at once would mean the cache always wins and
        // the real-time price would never be used. This gives the
        // authoritative source a head start and falls back only if it
        // is genuinely slow.
        select {
        case <-time.After(30 * time.Millisecond):
        case <-ctx.Done():
            // Still send. The loop below expects two values, and a
            // goroutine that returns without sending is exactly the
            // §14.3.7 deadlock -- one this would hit whenever the
            // caller has under 30ms left.
            ch <- attempt{err: ctx.Err(), tier: "cached"}
            return
        }
        p, err := priceCache.Get(ctx, id)
        ch <- attempt{p, err, "cached"}
    }()

    for range 2 {
        a := <-ch
        if a.err == nil {
            if a.tier == "cached" {
                slog.Info("served stale price", "product", id)
                stalePrices.Inc()
            }
            return a.price, nil
        }
    }
    return PriceInfo{}, fmt.Errorf(
        "all price sources failed for %s", id)
}

14.7.6 Making Degradation Visible

The worst partial failure is the one nobody notices. If the recommendation service is down and the page silently renders without it, the system “works”, delivers less, and stays that way.

// Illustrative snippet — not a complete program
type Quality int

const (
    Full     Quality = iota // everything present
    Degraded                // some optional data missing
    Minimal                 // critical data only
)

type PageResponse struct {
    Data    PageData
    Quality Quality  // how complete is this?
    Missing []string // what is absent?
}

Three signals, each for a different audience, and all three are needed:

// Illustrative snippet — not a complete program
if resp.Quality != Full {
    w.Header().Set("X-Response-Quality", resp.Quality.String())
    slog.Warn("serving degraded response",
        "product_id", id, "quality", resp.Quality,
        "missing", resp.Missing)
    metrics.DegradedResponses.Inc()
}

Without the metric, operations does not know. Without the log, they cannot debug it. Without the quality field, the caller cannot adapt. Miss any one and degradation becomes invisible at that layer.

14.7.7 Common Mistakes

Two need a note.

A shared deadline alone can starve the later tiers. Wrapping three tiers in one 5-second budget bounds the total, but the primary can consume all five seconds and leave nothing for the others — you have swapped 15 seconds of waiting for a guaranteed single attempt. The hybrid from §14.7.4 is the answer: a per-tier cap under an overall budget.

// Illustrative snippet — not a complete program
ctx, cancel := context.WithTimeout(ctx, 5*time.Second) // total budget
defer cancel()

for _, tier := range tiers {
    tierCtx, tierCancel := context.WithTimeout(ctx, 2*time.Second)
    d, err := tier.Get(tierCtx, id)
    tierCancel()
    if err == nil {
        return d, nil
    }
}

Sticky fallback flags never recover. if useFallback { return fallback.Get(...) } with a flag set on first failure means the primary is never tried again, so the system stays degraded after the outage ends — and the unsynchronised read and write of that flag is a data race the detector will flag. Make the fallback a per-request decision and recovery becomes automatic.

Summary: Partial Failure and Degraded Operation

Concurrent failure is a spectrum rather than a binary, and at any real fan-out width it is the normal state: at 1% per-goroutine failure, 63% of hundred-way requests have at least one failure. Designing as though “all succeeded” and “all failed” are the only cases means designing for something that rarely happens.

Collect every outcome and let the caller set the policy. When a function can return both useful data and a non-nil error, document that — silently breaking Go’s convention makes callers throw away results they could have used.

Four policies, and they compose. Classify goroutines doing different work as critical or optional. Threshold goroutines doing the same work against different sources. Bound with a deadline when latency matters more than completeness. Fall back from highest quality toward highest reliability, ending in graceful absence.

Then make it visible in three places at once — a quality field for the caller, a structured log for the on-call engineer, a metric for the dashboard. Degradation that nobody can see is not resilience; it is a permanent quality regression that has not been noticed yet.

Self-Check Questions: Partial Failure and Degraded Operation