errgroup as structured concurrency: scoped goroutines, first-error cancellation, and SetLimit

A scope for goroutines

When you fan out without a scope, you are trusting that every goroutine returns on its own — and one deaf sibling at 2 a.m. proves that trust wrong. A bare go statement is unstructured: the goroutine has no join point, its error has nowhere to go, and its lifetime is unrelated to the function that spawned it. Structured concurrency inverts that — concurrent work is bounded by a lexical region, and the region does not exit until every child has. In Go the idiom is errgroup:

func loadOrder(ctx context.Context, id string) (*Order, error) {
	g, ctx := errgroup.WithContext(ctx) // shadowed ctx: cancelled on first error

	var inv Inventory
	var price Pricing
	g.Go(func() error { return fetchInventory(ctx, id, &inv) })
	g.Go(func() error { return fetchPricing(ctx, id, &price) })
	g.Go(func() error { return checkFraud(ctx, id) })

	if err := g.Wait(); err != nil {
		return nil, err // first error; group ctx is already cancelled
	}
	return assemble(inv, price), nil
}

Three guarantees define the region. Wait returns only after every g.Go callback has returned — no child outlives the function. The error Wait returns is the first non-nil one any child produced. And with WithContext, the group context is cancelled as soon as that first failing callback returns — siblings get a shutdown signal without you wiring one. A quieter guarantee rides along: Wait is a happens-before edge, so the pattern above — each child writes its own variable, the parent reads them only after Wait — is race-free without a single mutex.

Cancellation is a signal, not a kill

Here is the subtlety the Hook paid 28 seconds for. errgroup cancels the context after the failing callback returns its error — and cancelling a context does nothing by itself. No goroutine is interrupted, no connection is closed unless something is watching ctx.Done(). In-flight siblings keep running until they observe cancellation, which means the leak rule for the whole unit: every g.Go body must have a return path through ctx. Pass the group ctx into every blocking call — http.NewRequestWithContext, db.QueryContext, and every channel operation wrapped in a select with a ctx.Done() case. A child that computes a hash in a tight loop for 4 seconds is just as deaf: it should check ctx.Err() between chunks. The compiler will not flag a sibling that ignores ctx; your p99 will.

First error wins — so design the failure policy

Internally the group keeps one error slot guarded by sync.Once: the first non-nil return is stored, every later error is discarded. That default encodes an all-or-nothing policy — perfect for “assemble a page from three mandatory calls”, wrong for “enrich 50 records, keep what succeeded”. For best-effort fan-out, do not return errors from the callbacks at all; record them:

errs := make([]error, len(parts))
var g errgroup.Group // no WithContext: nothing should cancel the siblings
for i, p := range parts {
	g.Go(func() error {
		errs[i] = process(p) // record per-slot; disjoint indices need no mutex
		return nil           // never trip the group
	})
}
_ = g.Wait()
return errors.Join(errs...) // nil only if every part succeeded

errors.Join gives you the full picture the group would have thrown away. And even in all-or-nothing mode, wrap each child’s error with identity — fmt.Errorf("pricing: %w", err) — because the one error that survives should at least say which of the twelve calls it came from. Choose the policy per fan-out, explicitly; the silent default has a way of becoming an accidental contract.

SetLimit: bounded parallelism built in

Fan-out over 10,000 items must not mean 10,000 concurrent goroutines hammering one downstream. Since errgroup got SetLimit, the bound is one line:

g, ctx := errgroup.WithContext(ctx)
g.SetLimit(8) // set before any Go; changing it while children are active panics
for _, item := range items {
	g.Go(func() error { return convert(ctx, item) }) // blocks while 8 are in flight
}
err := g.Wait()

The mechanism matters: when the limit is reached, g.Go blocks the caller. The spawning loop itself becomes a backpressured producer — memory stays bounded by the limit, not by the item count. TryGo is the non-blocking variant: it returns false instead of waiting, for reject-instead-of-queue designs. This is the same block-or-reject choice the backpressure lesson builds on.

WaitGroup, errgroup, or channels of results

Before you reach for a channel of results, ask: do you actually need every outcome as data, or do you just need the first failure and a clean join? Three tools, one decision. sync.WaitGroup is a pure join: no errors, no cancellation — right when children genuinely cannot fail, and a known trap otherwise (errors get logged into the void and the parent reports success). errgroup adds first-error propagation, sibling cancellation, and a concurrency limit — the default for fan-out with a failure policy. Channels of results are the heavyweight option: each worker sends a typed result or error, the consumer ranges and decides — necessary when you need every outcome as data, streaming order, or partial consumption, at the price of writing the close-and-drain choreography yourself (the pipelines lesson). Overhead is honest noise: errgroup is a WaitGroup plus a mutex, a Once, and an optional limiter channel — nanoseconds next to any call worth fanning out for.