Context — Find the Bug¶

1. How to use this file¶

Fourteen buggy snippets of context usage in Go: cancel-leaks, value-key collisions, struct-stored contexts, lost deadlines, busy spins, double-cancels, nil-ctx panics, WithoutCancel misuse. Read each in 30-60 seconds, decide where the defect is, then expand <details> for the answer.

Context bugs almost never blow up on the happy path. They silently leak a goroutine because nobody called cancel. They quietly drop a deadline because a leaf re-rooted on Background(). They collide on a string value key the moment a second package picks the same word. Four questions to ask every snippet:

1. Does every WithCancel/WithTimeout/WithDeadline have a defer cancel() reachable on every path?
2. Is the parent passed through unmodified — no context.Background() or context.TODO() substituted in the middle of a call chain?
3. Is the context ever stored on a long-lived struct or shared past the caller's return?
4. Are value keys unexported named types, not bare strings — and is every consumer prepared for ctx == nil?

If a snippet can't answer all four, there's a bug. Every diagnosis below references context/context.go from the Go 1.22 standard library by line number, so you can confirm the source-level reason rather than trusting the prose.

Bug 1 — WithCancel returned but cancel never called (goroutine leak)¶

import "context"

func fetchUser(parent context.Context, id string) (*User, error) {
    ctx, _ := context.WithCancel(parent)   // BUG: cancel discarded
    return store.Get(ctx, id)
}

func fetchUser(parent context.Context, id string) (*User, error) {
    ctx, cancel := context.WithCancel(parent)
    defer cancel()
    return store.Get(ctx, id)
}

Bug 2 — context.WithValue using a bare string key¶

const userIDKey = "user_id"

func WithUser(ctx context.Context, id string) context.Context {
    return context.WithValue(ctx, userIDKey, id)   // BUG: string key
}

func User(ctx context.Context) string {
    s, _ := ctx.Value(userIDKey).(string)
    return s
}

type userIDKeyT struct{}
var userIDKey userIDKeyT

func WithUser(ctx context.Context, id string) context.Context {
    return context.WithValue(ctx, userIDKey, id)
}
func User(ctx context.Context) string {
    s, _ := ctx.Value(userIDKey).(string)
    return s
}

Bug 3 — Storing context.Context in a struct field¶

type Service struct {
    ctx context.Context   // BUG: long-lived field
    db  *DB
}

func NewService(ctx context.Context, db *DB) *Service {
    return &Service{ctx: ctx, db: db}
}

func (s *Service) Find(id string) (*User, error) {
    return s.db.Get(s.ctx, id)   // uses whatever ctx was at construction
}

type Service struct{ db *DB }

func NewService(db *DB) *Service { return &Service{db: db} }

func (s *Service) Find(ctx context.Context, id string) (*User, error) {
    return s.db.Get(ctx, id)
}

Bug 4 — context.Background() substituted at a leaf (deadline lost)¶

func handler(ctx context.Context, w http.ResponseWriter, r *http.Request) {
    // ctx came from a WithTimeout(parent, 5*time.Second) higher up the stack.
    rows, err := db.QueryContext(context.Background(), "SELECT ...")   // BUG
    ...
}

rows, err := db.QueryContext(ctx, "SELECT ...")

Bug 5 — Goroutine selects on ctx.Done() but never reads it again¶

func worker(ctx context.Context, jobs <-chan Job) {
    for {
        select {
        case <-ctx.Done():
            // BUG: no return — falls through, loops forever
        case j := <-jobs:
            process(j)
        }
    }
}

func worker(ctx context.Context, jobs <-chan Job) {
    for {
        select {
        case <-ctx.Done():
            return
        case j := <-jobs:
            process(j)
        }
    }
}

Bug 6 — Forgot to check ctx.Err() after <-ctx.Done()¶

func runJob(ctx context.Context) error {
    done := launchAsync()
    select {
    case <-done:
        return nil
    case <-ctx.Done():
        return errors.New("job aborted")   // BUG: hides Canceled vs DeadlineExceeded
    }
}

case <-ctx.Done():
    return ctx.Err()   // returns Canceled or DeadlineExceeded

return fmt.Errorf("runJob: %w", ctx.Err())

Bug 7 — context.WithTimeout(parent, 0) (immediate cancel)¶

func quickCheck(parent context.Context, attempt int) error {
    d := time.Duration(attempt) * 100 * time.Millisecond
    ctx, cancel := context.WithTimeout(parent, d)   // BUG: d == 0 on attempt 0
    defer cancel()
    return ping(ctx)
}

if d <= 0 {
    return fmt.Errorf("quickCheck: non-positive timeout %v", d)
}
ctx, cancel := context.WithTimeout(parent, d)
defer cancel()

Bug 8 — context.WithDeadline(parent, time.Time{}) or a past time¶

func runUntil(parent context.Context, until time.Time) error {
    ctx, cancel := context.WithDeadline(parent, until)   // BUG when until is past/zero
    defer cancel()
    return loop(ctx)
}

if until.IsZero() || until.Before(time.Now()) {
    return fmt.Errorf("runUntil: deadline %v is not in the future", until)
}
ctx, cancel := context.WithDeadline(parent, until)
defer cancel()

Bug 9 — context.TODO() left in production code¶

func ChargeCard(amount int64) error {
    return paymentsAPI.Charge(context.TODO(), amount)   // BUG: shipped to prod
}

func ChargeCard(ctx context.Context, amount int64) error {
    return paymentsAPI.Charge(ctx, amount)
}

Bug 10 — Calling cancel() twice (works, but reads as bug)¶

func runQuery(parent context.Context) error {
    ctx, cancel := context.WithCancel(parent)
    defer cancel()

    err := doWork(ctx)
    if err != nil {
        cancel()           // BUG: redundant, misleading
        return err
    }
    return nil
}

func runQuery(parent context.Context) error {
    ctx, cancel := context.WithCancel(parent)
    defer cancel()

    if err := doWork(ctx); err != nil {
        return err
    }
    return nil
}

ctx, cancel := context.WithCancel(parent)
defer cancel()
result, err := doWork(ctx)
cancel() // release child slot before slow flush below
slowFlush(result)

Bug 11 — Passing nil as context¶

func ChargeCard(ctx context.Context, amount int64) error {
    return paymentsAPI.Charge(ctx, amount)
}

// caller
err := ChargeCard(nil, 100)   // BUG: nil Context

err := ChargeCard(context.Background(), 100)   // explicit root

Bug 12 — Race between cancel() and <-ctx.Done() on a custom Context¶

// Custom Context wrapping a real context, recording the deadline reason.
type tracingCtx struct {
    context.Context
    cancelled atomic.Bool
}

func (c *tracingCtx) Done() <-chan struct{} {
    if c.cancelled.Load() {
        return closedchan
    }
    return c.Context.Done()
}
// caller calls cancel() concurrently with another goroutine reading <-ctx.Done()

type tracingCtx struct {
    context.Context
    // observation only — never participate in cancellation
}
// inherit Done() and Err() unchanged; trace on Value lookup or out-of-band

Bug 13 — Returning a child context from a function that outlives the caller¶

func openSession(parent context.Context) context.Context {
    ctx, cancel := context.WithTimeout(parent, 30*time.Second)
    defer cancel()           // BUG: cancels before caller can use ctx
    return ctx
}

// caller
sessionCtx := openSession(reqCtx)
go process(sessionCtx)       // ctx is already cancelled

func openSession(parent context.Context) (context.Context, context.CancelFunc) {
    return context.WithTimeout(parent, 30*time.Second)
}

// caller
sessionCtx, cancel := openSession(reqCtx)
defer cancel()
go process(sessionCtx)

Bug 14 — Misuse of context.WithoutCancel (Go 1.21+): losing required cancellation¶

func writeAuditLog(ctx context.Context, event Event) {
    bgCtx := context.WithoutCancel(ctx)
    go func() {
        // BUG: bgCtx never times out, never cancels — runs forever on slow audit sink
        if err := auditSink.Write(bgCtx, event); err != nil {
            log.Printf("audit: %v", err)
        }
    }()
}

func writeAuditLog(ctx context.Context, event Event) {
    detached := context.WithoutCancel(ctx)            // keep request-id values
    bgCtx, cancel := context.WithTimeout(detached, 5*time.Second)
    go func() {
        defer cancel()
        if err := auditSink.Write(bgCtx, event); err != nil {
            log.Printf("audit: %v", err)
        }
    }()
}

Summary¶

These bugs cluster into four families.

Lifecycle (1, 10, 13, 14): discarding cancel, calling it twice, returning ctx without its cancel, using WithoutCancel without re-bounding. The (ctx, cancel) pair from withCancel (context.go:273) registers the child in the parent's cancelCtx.children map (context.go:436); only cancel(true, ...) (context.go:549) removes it. Lose ownership and you leak the registration — or strip cancellation entirely and never get it back.

Value semantics (2, 3, 11): string keys collide, struct fields freeze one request's ctx into a long-lived object, nil ctx panics on the first method dispatch. The doc on Context (context.go:36-44) and on WithValue (context.go:715-727) writes the rules; the linter ecosystem (go vet, staticcheck, containedctx, contextcheck) enforces them at CI time. The stdlib itself uses var cancelCtxKey int (context.go:374) — an unexported named type — as the canonical pattern.

Cancellation semantics (5, 6, 7, 8, 12): busy-loop on Done, swallow ctx.Err(), immediate-cancel via zero/past deadline, race on custom Context implementations. Done() is a one-shot broadcast (closed at context.go:564-568); after close, every receive returns the zero value forever. Err() (context.go:463) is the only way to learn why. WithDeadline (context.go:625) and WithTimeout (context.go:703) short-circuit on non-positive durations — boundary inputs must be validated by the caller, not by the constructor.

Propagation (4, 9): substituting Background() or TODO() mid-stack throws the parent's deadline, cancellation, and values away. emptyCtx (context.go:181-197) returns zero from every method. Static rule: if the function already takes a ctx context.Context, the function does not construct a new root — it threads what it received.

Review checklist for any context-using PR:

• Does every WithCancel/WithTimeout/WithDeadline/WithCancelCause have a reachable defer cancel() on every return path? go vet's lostcancel is the cheapest catcher.
• Are all context.WithValue keys unexported named types (e.g., type userIDKey struct{}), never string or any built-in? go vet's contextkey flags it.
• Does any struct hold a context.Context field? If yes, refactor — pass ctx as the first parameter of each method instead. containedctx lints this.
• Does any function that receives a ctx context.Context ever create context.Background() or context.TODO() mid-body? contextcheck flags it; replace with the received ctx or with context.WithoutCancel(ctx) if the detachment is deliberate.
• Does every <-ctx.Done() arm of a select return (or break out of the surrounding loop)? An empty arm is a busy spin.
• When a <-ctx.Done() fires, does the error path return ctx.Err() (or wrap it with %w) so callers can errors.Is(err, context.DeadlineExceeded)?
• Are all WithTimeout/WithDeadline durations validated > 0 and deadlines validated .After(time.Now()) before the call? Boundary inputs (env vars, JSON 0, zero time.Time) must be screened.
• Are nil contexts forbidden at every callsite? Use context.Background() (deliberate root) or context.TODO() (temporary, with a TODO comment); never nil.
• If a function returns a context it created, does it also return the matching cancel? Match the stdlib shape (Context, CancelFunc).
• If context.WithoutCancel is used, is the detached context re-bounded with a fresh WithTimeout before any I/O?
• Are there any custom Context implementations? If yes, do they compose via embedding without overriding Done/Err, or do they atomically gate transitions under a single mutex the way cancelCtx does (context.go:549-583)?