Go Guides

Go errgroup Worker Pool: The Race the Compiler Won't Catch

A worker pool with a shared slice and a shared counter compiles clean, runs, and prints a plausible total. It is still wrong. This guide builds that pool with errgroup, runs it under the race detector, reads the five data races in the report, fixes the pool with one mutex, and measures the rest of the API on the way: the SetLimit ceiling, the cancellation timing, the deadlock that comes from launching the failing task last, and the TryGo and SetLimit(0) edges.

Written November 7, 2026 · Tested with Go 1.27.3 · 19 min read

By the end of this guide
  • The pool
  • What the compiler misses
  • Running the failing control
  • The wrong number is the lesson

The pool

The program is a small worker pool. Four workers pull jobs from a channel, square each job number, and record the result in two places: a shared slice and a shared counter. The group caps the workers at four with SetLimit, and Wait blocks until every worker has finished:

Go
package main

import (
    "fmt"
    "sync"

    "golang.org/x/sync/errgroup"
)

func main() {
    var g errgroup.Group
    g.SetLimit(4)
    jobs := make(chan int)
    var results []int
    count := 0
    var mu sync.Mutex // used only by the fixed run (see below)
    _ = mu
    for w := 0; w < 4; w++ {
        g.Go(func() error {
            for j := range jobs {
                results = append(results, j*j) // RACE: unsynchronised slice write
                count++                        // RACE: unsynchronised counter
            }
            return nil
        })
    }
    for j := 1; j <= 20; j++ {
        jobs <- j
    }
    close(jobs)
    if err := g.Wait(); err != nil {
        fmt.Println("errgroup error:", err)
    }
    fmt.Println("count:", count, "results:", len(results))
}

Nothing here looks broken at a glance. The program compiles with no warnings, runs to completion, and prints a count and a result length. The compiler has no complaint because nothing in the code violates a compile-time rule: the slice and the counter are ordinary variables, and four goroutines writing them at the same time is a runtime property, not a type error. That is the whole point of this guide. The bug is real, the compiler cannot see it, and the only thing standing between this program and production is a test run with the right flag.

The setup for every run in this guide is the same: Go 1.27.3, golang.org/x/sync v0.24.0, on a Linux amd64 machine. The errgroup package is not in the standard library; it lives in golang.org/x/sync, so the module needs that dependency before any of this runs.

What the compiler misses

A data race happens when two goroutines touch the same variable at the same time and at least one of them writes. That is the definition the Go race detector documentation gives, and it is exactly what this pool does: four workers append to results and bump count with no lock, no channel, and no atomic operation between them.

Two details make this race easy to miss in review. First, append is not one write. It reads the slice header, writes the new element, and writes back a new header, and when the slice grows it allocates a new backing array and copies the old contents. Two workers doing that at once can lose each other's elements, which is why the result length comes out short. Second, count++ is not one step either. It reads the counter, adds one, and writes it back, so two workers can read the same value and both write back the same incremented number, losing one count.

The program still finishes. Wait returns no error, because no worker returns one. The only visible symptom without the detector is a wrong number, and the wrong number changes from run to run, which makes it look like flakiness instead of a bug.

Running the failing control

The race detector is a test gate, not a linter. It runs the program with instrumentation and reports races that actually happen while it runs. The flag is -race, and it works with go run as well as go test:

Command
$ go run -race .

Run against the buggy pool, that command exits 1 and prints five WARNING: DATA RACE blocks, followed by the lines:

Output
count: 20 results: 12
Found 5 data race(s)
exit status 66

The exit status 66 is the detector's own default exit code for a detected race, stated in the race detector documentation. The go run wrapper reports that as its own exit code 1. The count line is the teaching point, and it needs reading carefully: the counter says 20, the slice holds 12 results, and 20 jobs went in. Both numbers are wrong in different ways. The counter happened to land on 20 this time, which looks right and is not. The slice lost 8 results to concurrent appends. A program that prints the right-looking number is more dangerous than one that prints an obviously wrong one, because the right-looking number passes a casual check.

The first race in the report points at the exact lines:

Output
WARNING: DATA RACE
Read at 0x00c000124030 by goroutine 8:
  main.main.func1()
      /home/user/go-race-probe-2026-11-06/buggy/main.go:24 +0x9b
  golang.org/x/sync/errgroup.(*Group).Go.func1()
      /home/user/go/pkg/mod/golang.org/x/sync@v0.24.0/errgroup/errgroup.go:93 +0x86

Previous write at 0x00c000124030 by goroutine 8:
  main.main.func1()
      /home/user/go-race-probe-2026-11-06/buggy/main.go:24 +0x114

Line 24 is the results = append(results, j*j) line, and the stack runs through errgroup.go:93, the line inside Group.Go where the worker function runs. The report also gives the goroutine creation stacks, so the race is traceable to the g.Go call that started each worker. The other four blocks cover the same two lines from the other direction: writes against writes on the slice, and reads and writes on the counter at line 25.

The wrong number is the lesson

The buggy pool was run three times in a row on the same machine, same binary shape, same 20 jobs. The race count was 5 every time. The results were not:

Run Exit code Data races Count Results
1 1 5 20 12
2 1 5 20 9
3 1 5 20 18

A fourth run, the day before on the same pool, reported 6 races with a count of 18 and 18 results. The counter reads 20 in all three of today's runs, which is the correct-looking answer, and it is still the product of lost increments that happened to cancel out. The slice length swings from 9 to 18 out of 20. Nothing about the program changed between runs. The scheduling changed, and the scheduling decides which increments and appends collide.

That variance is the reason the detector matters more than the output. If the test asserts on the printed total, it passes on the days the counter lands on 20 and fails on the days it does not. The detector fails the run every time, because it watches the accesses instead of the outcome. The failing control is the point: run the buggy version first, watch it fail, and only then trust the fixed version's pass.

A second pool shows the same shape in test form. Fifty fetch tasks, each returning 1, run through a racy pool with a limit of 8, then through the fixed pool. Under go test -race, the racy test fails with 5 WARNING: DATA RACE blocks and logs a total of 50, which is the right answer produced by a broken program. The fixed test passes with 50 results and a total of 50. The same racy test logged 49 on an earlier run. The total is unreliable even when it reads correctly; the detector's verdict is the stable signal.

The fix: one mutex

The fix guards both shared writes with one mutex. Nothing else in the program changes:

Go
for w := 0; w < 4; w++ {
    g.Go(func() error {
        for j := range jobs {
            mu.Lock()
            results = append(results, j*j)
            count++
            mu.Unlock()
        }
        return nil
    })
}

Run under the detector, the fixed pool exits 0 with no race report and prints:

Output
count: 20 results: 20

The lock covers the append and the increment together, so the two numbers cannot drift apart: a worker that appends also counts, in the same critical section. An alternative fix is to give each worker its own slice and merge the pieces after Wait, or to send results back over a channel and let one goroutine own the slice. All three shapes remove the shared write. The mutex is the smallest change, and it keeps the program's shape so the before-and-after comparison is honest: the only difference between the failing run and the passing run is the lock.

A passing detector run needs one careful reading. The race detector documentation states that it only finds races that happen at runtime, so it cannot find races in code paths that are not executed. Silence from -race means no race was observed in the paths this run executed. It does not mean the program is race-free. The claim this guide makes for the fixed pool is exactly that: 20 jobs, 4 workers, one run under -race, no race observed, count 20, results 20.

The ceiling: SetLimit is a hard cap

SetLimit caps the number of active goroutines in the group. The documentation states the rule plainly: a negative value means no limit, a limit of zero prevents any new goroutines from being added, and the limit must not be modified while any goroutines in the group are active. The measured version of that rule is a probe with 200 tasks and a limit of 8, tracking the highest number of tasks in flight with an atomic counter:

Output
ceiling: tasks=200 limit=8 max-in-flight=8

Two hundred tasks went through a group limited to 8, and the peak concurrency was exactly 8, never above it. The ceiling is saturated, not approximate: all 200 tasks ran, and at no point did a ninth goroutine join them. That is the property a bounded pool is bought for. Without the limit, a group with no SetLimit call runs every task it is given, and a burst of input becomes a burst of goroutines.

A zero Group with no limit set is valid, and the documentation says so directly: it has no limit on the number of active goroutines and does not cancel on error. The limit is opt-in. The cancellation behavior below only exists when the group comes from WithContext.

Cancellation: the failer goes first

WithContext returns a group and a derived context. The documentation states that the derived context is canceled the first time a function passed to Go returns a non-nil error, or the first time Wait returns, whichever comes first. The probe that measures this launches the failing task first, then 7 siblings that wait on the context, all inside a limit of 8:

Go
g, ctx := errgroup.WithContext(context.Background())
g.SetLimit(8)
t0 := time.Now()
g.Go(func() error {
    time.Sleep(50 * time.Millisecond)
    return errors.New("boom-first-error")
})
for i := 0; i < 7; i++ {
    g.Go(func() error {
        <-ctx.Done()
        fmt.Printf("cancel: sibling returned at +%v ctx.Err=%v\n", time.Since(t0).Round(time.Millisecond), ctx.Err())
        return nil
    })
}
err := g.Wait()
fmt.Printf("cancel: Wait returned err=%v after %v; ctx.Err()=%v; context.Cause(ctx)=%v\n",
    err, time.Since(t0).Round(time.Millisecond), ctx.Err(), context.Cause(ctx))

The output, re-run for this guide:

Output
cancel: sibling returned at +51ms ctx.Err=context canceled
cancel: sibling returned at +51ms ctx.Err=context canceled
cancel: sibling returned at +51ms ctx.Err=context canceled
cancel: sibling returned at +51ms ctx.Err=context canceled
cancel: sibling returned at +51ms ctx.Err=context canceled
cancel: sibling returned at +51ms ctx.Err=context canceled
cancel: sibling returned at +51ms ctx.Err=context canceled
cancel: Wait returned err=boom-first-error after 51ms; ctx.Err()=context canceled; context.Cause(ctx)=boom-first-error

All 7 siblings returned at 51 milliseconds, one millisecond after the failer fired at 50. Wait returned the failer's error, boom-first-error, after 51 milliseconds, and context.Cause on the derived context gives the same error. The count is worth re-checking: 7 sibling lines, not 8, because the eighth slot holds the failer. Cancellation is fast here because the siblings are waiting on the context. A sibling in the middle of a slow fetch that never checks the context would keep running until the fetch finished; cancellation signals, it does not interrupt. The probe's siblings return in a millisecond because waiting on ctx.Done() is the whole job.

Wait returns the first non-nil error from the group. If two tasks fail, only the first error comes back. The other error is recorded nowhere. That is the documented behavior, and it shapes how the pool reports failure: the first error is the signal, and anything the caller needs from later errors has to be collected inside the tasks themselves.

The deadlock trap: launch the failer first

Trap
The cancellation probe above works because the failer launches first. Launch it last and the program dies. With a limit of 8 and 8 siblings already holding all 8 slots, each waiting on a context that only the failer can cancel, the Go call for the failer blocks in main forever: it cannot add a ninth goroutine until a slot frees, and no slot frees until the context cancels, and the context cancels only when the failer runs. The runtime notices that every goroutine is asleep and kills the program:
Output
8 siblings hold all 8 slots; calling Go for the failer now
fatal error: all goroutines are asleep - deadlock!
goroutine 1 [chan send]:
    /home/user/go/pkg/mod/golang.org/x/sync@v0.24.0/errgroup/errgroup.go:74 +0x34

The stack shows main blocked at errgroup.go:74, the line in Group.Go that sends on the semaphore channel. The failer never starts; the "failer started" line never prints. This shape was run for this guide and died the same way on the earlier probe run, where the runtime reported exit status 2. The go run wrapper in this run reported exit code 1.

The rule that follows is mechanical, not stylistic: the task that must fire cancellation has to start before the limit fills, or the siblings have to number fewer than the limit so a slot stays open. Seven siblings plus one failer inside a limit of 8 works. Eight siblings plus one failer inside a limit of 8 deadlocks. Never present the eight-siblings-then-failer shape as working code. It is the failing example, and it belongs in a guide only with the fatal error attached.

The same blocking rule explains why Go must be called before Wait. The documentation says the first call to Go must happen before a Wait, and Go blocks until the new goroutine can be added without exceeding the limit. A Go call made after the group has filled up waits for a slot. If nothing ever frees one, it waits forever.

TryGo: the non-blocking alternative

TryGo is the call for code that cannot afford to block. It starts the goroutine only when the number of active goroutines is currently below the limit, and it reports whether the goroutine started. With a limit of 2 and both slots full, the probe reports:

Output
trygo: TryGo while full returned false started=2 (expect false/2)
trygo: Wait clean

The caller gets false and the count of started goroutines stays at 2. Wait then returns cleanly. The difference from Go is the whole API: Go waits for a slot, TryGo answers immediately. The caller has to handle the false case, by queuing the work, dropping it, or retrying later. A TryGo whose return value is ignored is a silent task drop, which is worse than a blocked Go in most programs: the work vanishes with no error and no log line.

SetLimit(0), negative limits, and changing the limit mid-flight

The limit edges were probed one at a time. SetLimit(0) makes TryGo return false with zero goroutines started, and a Go call stays blocked after 200 milliseconds:

Output
limit0: TryGo returned false started=0
limit0: Go still blocked after 200ms (matches doc: zero prevents adds)

The documentation's sentence is "a limit of zero will prevent any new goroutines from being added," and the pinned source shows why: a limit of zero builds an unbuffered semaphore channel, so Go blocks sending on it until another goroutine's completion receives, and with no goroutines running there is no completion coming. A zero limit is not "unlimited with a different spelling." It is a closed gate. A negative limit is the unlimited spelling: with SetLimit(-1) and no goroutines active, 20 tasks ran and 20 completed.

Changing the limit while the group is busy is where the API bites. A positive SetLimit call while goroutines are active panics with the message errgroup: modify limit while 4 goroutines in the group are still active. The negative case is the trap inside the trap: SetLimit(-1) with 4 goroutines active does not panic, because the source returns early for negative values before it reaches the active check. So the flat statement "changing the limit while the group is active panics" is wrong. The accurate statement is that raising or setting a non-negative limit while goroutines are active panics, and removing the limit with a negative value does not. Set the limit once, before the first Go call, and the question never comes up.

The producer leak

In the jobs-channel pool, main sends jobs into an unbuffered channel while the workers receive. If a worker returns an error and the context cancels, the remaining workers can exit while main is still blocked sending the next job, with no receiver left. main would then never reach Wait, and the program would hang with no error and no output.

The guard for that shape is in the errgroup documentation itself, in the Pipeline example: the producer sends inside a select that also watches ctx.Done(), and returns the context's error when the context fires. That is the documented pattern, and it is the one to copy.

A panic in a worker is not an error

A worker that panics does not return an error, and errgroup does not recover it. A worker that panicked crashed the program with its own stack trace and exit code 1. The pinned source carries a comment explaining the choice: propagating panics to the Wait caller would delay them arbitrarily, turn the panic stack into a mere value, and risk deadlocks that hide the panic entirely. The consequence for pool design is direct: a task that can panic needs its own recover inside the task function if the program is meant to survive it. Errgroup will not do that work.

What -race costs and what it cannot do

The detector is not free. The race detector documentation puts the cost for a typical program at 5 to 10 times the memory and 2 to 20 times the execution time. It also requires cgo to be enabled and, on Linux, an installed C compiler. Those costs are why -race belongs in tests and in pre-release runs rather than in a production binary, and why a pool that passes under -race in a test still deserves a run under a realistic workload: the documentation advises exactly that, because the detector only finds races in paths that execute.

The practical rule for this pool is short. Run the buggy version under -race first and keep the failing output. Fix the shared state, run it again, and keep the passing output next to it. The two runs together are the evidence. Either one alone is a claim.

Frequently asked questions

Does errgroup protect my shared state?

No. The group synchronizes goroutine lifetimes and propagates the first error. It knows nothing about the variables the workers touch. A slice, a counter, and a map are all unprotected unless the program guards them with a mutex, a channel, or atomics. The race detector report in this guide points at the program's lines, not at errgroup's.

Why not just use a WaitGroup and a semaphore channel?

That combination works, and errgroup is built from exactly those pieces: a sync.WaitGroup and a buffered channel used as a semaphore. The group adds two things on top: the limit is one call instead of a hand-rolled channel, and the first error cancels a shared context. If the program needs neither, a WaitGroup is enough. If it needs both, the group is the smaller code.

Should every pool use SetLimit?

Every pool with an unbounded input should. The input decides how many tasks exist; the limit decides how many run at once. Without the limit, a burst of input is a burst of goroutines, and the pool's memory and connection use follow the input instead of the machine. The ceiling probe shows the limit holds exactly: 200 tasks, limit 8, peak 8.

Can I call SetLimit after the group has started?

Only to remove the limit with a negative value, which does not panic. Setting a non-negative limit while goroutines are active panics. The safe shape is one SetLimit call before the first Go call.

What does a clean -race run prove?

That no race was observed in the code paths this run executed. It does not prove the program is race-free. Run the detector under a realistic workload as well as in tests, and keep the failing control around so a future change that reintroduces the race fails loudly instead of silently.

What comes next?

Testing that timing deterministically, without waiting out real seconds, is the next step: Go's synctest bubble runs a 5-second deadline in virtual time. The sibling guide for this pool's cancellation test covers that.

Sources

  • Go Packages, golang.org/x/sync/errgroup — the Group API: WithContext cancellation on first error or first Wait return, Go blocking until under the limit, SetLimit with negative meaning no limit and zero preventing adds, TryGo reporting whether the goroutine started, Wait returning the first non-nil error, and the Pipeline example's producer guarded by ctx.Done().
  • Go, Data Race Detector — the definition of a data race, the -race flag for go test, go run, go build, and go install, the report format, the default exit code 66, the statement that the detector only finds races that happen at runtime, and the runtime overhead of 5–10x memory and 2–20x execution time.
  • Go, Package context — WithCancelCause and Cause, which the cancellation probe's output relies on.

Keep Exploring