Go errgroup SetLimit: Why Cancellation Does Not Stop Admission

Your batch worker caps concurrency with errgroup.SetLimit(4). A request is canceled, so you expect the submission loop to stop admitting work. That expectation mixes two different mechanisms: a limit controls available slots; a context signals that work should stop. In the pinned implementation examined here, filling a slot does not consult the context.

The practical question is not whether errgroup supports cancellation. It does. The question is where cancellation is checked, and whether a caller waiting to submit another function can abandon that wait. Answering it requires following the implementation across admission, execution, and joining—not just adding WithContext to a batch loop.

This complements the Python Requests timeout and retry guide: transport timeouts and retry budgets solve a different problem from admitting concurrent tasks. Neither layer automatically supplies the other’s guarantees.

On this page

1. Evidence and method: inspect one pinned errgroup release
2. Trace admission, task execution, and Wait separately
3. Reproduction: three assertions without a timing benchmark
4. Read the assertions as contracts, not performance results
5. Choose where cancellation-aware admission belongs
6. Failure modes: nested submission and misleading fixes
7. Limitations of this source-level evidence
8. Action checklist: audit one batch boundary

Evidence and method: inspect one pinned errgroup release#

Source inspection timestamp: 2026-11-09T17:59:10Z. The evidence mode is pinned_release_analysis. The baseline is golang.org/x/sync v0.17.0, selected for a reproducible source reading, not presented as the newest release or an upgrade recommendation.

The official repository’s tag-reference response identifies the commit. The commit-addressed errgroup implementation and upstream tests provide the checkable artifacts. The following observations come from those files, not from running a workload:

• The v0.17.0 tag resolved to commit 04914c200cb38d4ea960ee6a4c314a028c632991 when inspected.
• With a limit configured, Go sends to the semaphore before adding the task to the WaitGroup, and that send does not select on context cancellation.
• TryGo checks semaphore capacity but does not check whether the associated context is canceled.
• Wait waits for the registered functions, cancels the derived context, and returns the stored task error without substituting the parent context error.
• The pinned TestWithContext cases expect the derived context to be canceled after Wait, including cases with no task error.

The original analysis below connects those operations into a failure path and supplies reader-runnable assertions. A commit identifier makes the inspected revision explicit; it does not certify application correctness. The distinction between artifact identity and trust is also covered in what SHA-256 checksums prove.

Trace admission, task execution, and Wait separately#

In Go, the semaphore send happens synchronously in the submitting goroutine. Only after that succeeds does the method register work and launch the function. When capacity is exhausted, the caller waits at admission. There is no branch there that watches the derived context.

Inside the launched function, your code owns cooperation with cancellation. The Go team’s context explanation describes Done as a signal that functions should abandon work and return. It is not a mechanism that forcibly terminates arbitrary goroutines. Passing a context and observing it are different actions.

Boundary	Pinned mechanism	Design consequence
Admission	Semaphore send before goroutine creation	A full limit can block the caller even after cancellation.
Execution	Your function returns an error or nil	Operations must observe cancellation or have another bounded exit.
Joining	WaitGroup wait, context cancellation, stored error return	Wait does not return early merely because the parent was canceled.

The version-specific package reference documents that Wait returns the first non-nil task error. If every function returns nil, canceling the parent does not by itself populate that error. Conversely, a successful Wait still cancels the derived context. Do not use that derived context for a follow-up operation after joining the group.

Reproduction: three assertions without a timing benchmark#

Use a supported Go toolchain capable of building the pinned module, plus network access for dependency resolution. Work in a new disposable directory rather than changing an application’s dependency graph. These commands create only the example module and its dependency records.

1. Create an empty directory and initialize the example module with the first command block.
2. Save the Go test block as admission_test.go in that directory.
3. Run the final command block to execute the three tests against golang.org/x/sync v0.17.0.
4. Compare the assertions with Go, TryGo, Wait, and TestWithContext in the pinned source files.

mkdir errgroup-boundary
cd errgroup-boundary
go mod init example.com/errgroup-boundary
go get golang.org/x/sync@v0.17.0
go list -m golang.org/x/sync

Save this complete file as admission_test.go. It uses channels to establish ordering instead of guessing how much scheduling time a sleep provides.

package boundary

import (
    "context"
    "errors"
    "testing"

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

func TestGoAdmitsCanceledContext(t *testing.T) {
    parent, cancel := context.WithCancel(context.Background())
    defer cancel()
    g, ctx := errgroup.WithContext(parent)
    g.SetLimit(1)

    release := make(chan struct{})
    g.Go(func() error {
        <-release
        return nil
    })

    cancel()
    <-ctx.Done()
    denied := !g.TryGo(func() error { return nil })
    close(release)

    seen := make(chan error, 1)
    g.Go(func() error {
        seen <- ctx.Err()
        return nil
    })
    if err := g.Wait(); err != nil {
        t.Fatalf("Wait = %v; want nil", err)
    }
    if !denied {
        t.Fatal("full limit admitted an extra task")
    }
    if err := <-seen; !errors.Is(err, context.Canceled) {
        t.Fatalf("task context = %v; want canceled", err)
    }
}

func TestTryGoAdmitsCanceledContext(t *testing.T) {
    parent, cancel := context.WithCancel(context.Background())
    defer cancel()
    g, ctx := errgroup.WithContext(parent)
    g.SetLimit(1)
    cancel()
    <-ctx.Done()

    seen := make(chan error, 1)
    if !g.TryGo(func() error {
        seen <- ctx.Err()
        return nil
    }) {
        t.Fatal("free slot rejected the task")
    }
    if err := g.Wait(); err != nil {
        t.Fatalf("Wait = %v; want nil", err)
    }
    if err := <-seen; !errors.Is(err, context.Canceled) {
        t.Fatalf("task context = %v; want canceled", err)
    }
}

func TestSuccessfulWaitCancelsContext(t *testing.T) {
    g, ctx := errgroup.WithContext(context.Background())
    g.Go(func() error { return nil })
    if err := g.Wait(); err != nil {
        t.Fatalf("Wait = %v; want nil", err)
    }
    if !errors.Is(ctx.Err(), context.Canceled) {
        t.Fatalf("context after Wait = %v; want canceled", ctx.Err())
    }
}

go test -run 'Test(GoAdmitsCanceledContext|TryGoAdmitsCanceledContext|SuccessfulWaitCancelsContext)$' -count=1 -timeout=10s .

The test timeout is a guard against a hung example, not a measured cancellation target. The test names and failure messages are authored assertions; no terminal output or passing execution is claimed here.

Read the assertions as contracts, not performance results#

The first test occupies the only slot with a function held on a channel. It cancels the parent, confirms that TryGo rejects admission while capacity is full, then releases the function. A subsequent Go call admits another function even though that function sees an already-canceled context.

Both functions deliberately return nil. That choice separates the parent signal from errgroup’s stored task error: the assertion expects Wait to return nil. Application code that instead returns ctx.Err() would supply a task error for the group to report.

The second test removes capacity pressure and isolates TryGo: free capacity permits admission after cancellation. The third isolates successful joining: Wait returns nil while the derived context becomes canceled. The upstream TestWithContext cases corroborate this last expectation.

These assertions do not measure how long a blocked Go call remains blocked. The no-cancellation-branch finding comes from inspecting its semaphore send. Keeping source inference separate from runtime measurement avoids turning a scheduler-dependent demonstration into a stronger claim than it supports.

Choose where cancellation-aware admission belongs#

For a finite batch of independent tasks, SetLimit can be a reasonable choice. Check the context before submitting each task and again inside the task before expensive work. The outer check reduces unnecessary submissions; it cannot cancel a semaphore send that has already started. The inner check protects work after admission; it does not make admission itself interruptible.

If interrupting a waiting producer is a requirement, consider a fixed worker pool with a bounded jobs channel. Start the consumers before the producer can block, and let the producer select between sending a job and receiving cancellation. The official pipelines and cancellation article explains this pattern, including why abandoned receivers otherwise leave senders stuck.

A cancellation-aware select still is not an absolute prohibition on admitting one more item: when sending and cancellation are both ready, either case can be selected. Workers should check cancellation before doing expensive work. If the requirement is a strict acceptance cutoff, define and synchronize that state transition explicitly instead of treating a context signal as an atomic admission policy.

Keep the pool’s bounds legible. Worker count limits active processing; channel capacity limits queued items. Neither alone limits the bytes held by each item or a result slice. A producer, workers, and a collector also need clear ownership of channel closure and a path to exit when another stage fails.

Failure modes: nested submission and misleading fixes#

Nested calls can create a dependency cycle. With a limit of one, an active function that calls Go on the same group waits for the slot it already occupies. That slot is released only after the outer function returns. Canceling the context cannot break this particular semaphore wait. Flatten submission outside the limited tasks or use a separately designed child-work mechanism.

A goroutine around every submission moves the queue. Wrapping each g.Go call in another goroutine can leave an unbounded number of submitters waiting for slots. It also complicates joining: the source registers a task only after admission. Finish or otherwise coordinate submission before treating Wait as the final barrier; follow the reference’s first-call-before-Wait rule.

TryGo requires an explicit rejection policy. Its false result means the function was not started. Decide whether to reject the item, queue it within a separate bound, or process it through a deliberate fallback. A busy loop around TryGo supplies neither fair scheduling nor a cancellation policy. Running rejected work inline also means the group’s limit no longer describes all active work.

Zero is not a pause switch. The pinned contract says a zero limit prevents new goroutines and forbids changing the limit while group goroutines are active. Configure a positive limit before starting work. Do not implement live resizing or shutdown by changing that setting underneath running functions.

Limitations of this source-level evidence#

• This analysis inspects public source and tests; the supplied commands were not executed for this article.
• The findings are pinned to golang.org/x/sync v0.17.0 and do not establish behavior for every release.
• The examples do not measure throughput, memory use, fairness, or cancellation latency.
• Context cancellation cannot stop application code that does not observe it or otherwise return.

The source can establish control flow, but it cannot choose a safe concurrency count for your downstream service. Nor can these small assertions establish that a database driver, network operation, or application callback returns promptly. Those are separate integration tests with their own deadlines and failure cases.

Action checklist: audit one batch boundary#

1. Pin the subject. Record the module version your application actually builds; compare its implementation with this baseline before carrying the conclusions forward.
2. Name each wait. Separate waiting for admission, waiting inside an operation, and waiting for all tasks to return. Identify who can unblock each one.
3. Choose failure semantics. Decide whether the caller needs the first task error, parent cancellation when tasks return nil, or a separately collected set of results. Implement that policy explicitly.
4. Keep context lifetimes separate. Use the group’s derived context for group work, not for follow-up work after a successful Wait.
5. Test both sides of capacity. Add a canceled-parent case with a free slot, one with a full slot, and a successful-join case. Also check that no active task submits blocking work into its own saturated group.

Start with one submission loop: mark its admission point and ask what releases it after cancellation. If the answer is only “another function eventually returns,” decide whether that is the contract you intended.