Go Gotcha #8: Context Cancellation Doesn't Propagate Unless You Wire It
Meta: "Go context cancellation only works if you explicitly pass it. Here's the wiring mistake that leaves goroutines running long after a request dies."
T
he request timed out. The client gave up and retried. Your Go service got the cancellation signal and then kept running the original request anyway. The database query finished. The downstream API call went out. The cache got written. All of it wasted, none of it cancelled, and now you have two competing operations in flight for a request that no longer exists.Context cancellation in Go is opt-in at every step. It doesn't propagate automatically. It propagates only as far as you explicitly pass it and most codebases have at least one place where they forget.
How Context Cancellation Actually Works
Go's context.Context is a signal-passing mechanism. When a parent context is cancelled whether by timeout, deadline, or an explicit cancel() call all contexts derived from it are cancelled too. Any code that checks ctx.Done() or passes that context to a blocking call will unblock and return an error.
The mechanism is clean. The catch is "derived from it."
When you call context.WithCancel(parent) or context.WithTimeout(parent, d), you create a new context linked to the parent. Cancel the parent, and the child gets cancelled. But if you call context.Background() anywhere in the chain to create a new root context you've severed the link. That goroutine is now running against an immortal context. It will not respond to the upstream cancellation.
This is the core of the gotcha. It doesn't look wrong. The code compiles. The happy path works fine. The bug only surfaces when something upstream cancels a client timeout, a load balancer cutting a connection, an HTTP handler hitting its deadline and the downstream work keeps running.
The Three Most Common Places Teams Get This Wrong
Database calls with a background context. This is the most common one. A function deep in the service layer creates its own context for a query: ctx := context.Background(). It does this because the query "needs to finish even if the request was cancelled." Sometimes that's intentional. Often it's habit, or copied from a Stack Overflow snippet. Either way, the database call is now immune to upstream cancellation. Under load, these pile up. The connection pool fills with queries for requests that no longer exist.
Goroutines spawned inside a handler without inheriting context. A request handler spawns a goroutine to do background work. The goroutine captures a context.Background() or no context at all. The handler returns. The client moves on. The goroutine runs until it finishes or the process dies. Multiply this across high request volume and you get the goroutine leak pattern described in Go Gotcha #1.
Third-party library calls that don't accept a context. Sometimes the library is the problem. An older SDK or client doesn't expose a context-aware API. In this case you have two options: wrap the call in a goroutine, use select to race it against ctx.Done(), and discard the result if the context cancels first. Or file a bug against the library. Neither is pleasant, but abandoning context propagation entirely is worse.
Wiring It Correctly
The rule is simple: every function that does I/O, calls another service, or spawns a goroutine should accept a context.Context as its first argument. Pass the incoming context down. Let the caller control lifetime.
Here's the key insight most articles skip: context checking only happens at the leaf functions the ones actually doing I/O. Intermediate callers don't need to check ctx.Done() themselves. They just pass the context down and propagate whatever error comes back.
Untitled1// Handler owns the context, passes it down2func handleCreateOrder(w http.ResponseWriter, r *http.Request) {3 order, err := createOrder(r.Context(), payload)4 if err != nil {5 // context.Canceled or context.DeadlineExceeded means client left6 // either way: return, don't panic, don't retry7 http.Error(w, err.Error(), http.StatusInternalServerError)8 return9 }10}1112// Mid-level passes ctx through, no select, no Done() check13func createOrder(ctx context.Context, p Payload) (*Order, error) {14 user, err := fetchUser(ctx, p.UserID) // leaf checks ctx15 if err != nil { return nil, err }1617 inv, err := reserveInventory(ctx, p) // leaf checks ctx18 if err != nil { return nil, err }1920 return saveOrder(ctx, user, inv) // leaf checks ctx21}2223// Leaf this is where context is actually checked24func fetchUser(ctx context.Context, id string) (*User, error) {25 row := db.QueryRowContext(ctx, "SELECT * FROM users WHERE id = $1", id)26 // QueryRowContext blocks until query completes OR ctx cancels27 // ...28}
The three-layer chain has zero select statements in the middle layer. The check happens once, inside QueryRowContext, at the actual I/O boundary.
How QueryRowContext does it and how to replicate it
Looking at what Go's database/sql actually does internally gives you the pattern for any custom blocking operation:
Untitled1// Simplified what QueryRowContext does under the hood2func queryWithContext(ctx context.Context, query string) (*Rows, error) {3 // Start the actual work in a separate goroutine4 resultCh := make(chan queryResult, 1)5 go func() {6 rows, err := executeQuery(query) // the real blocking call7 resultCh <- queryResult{rows, err}8 }()910 // Race: work finishes vs context cancelled11 select {12 case <-ctx.Done():13 return nil, ctx.Err() // ctx.Err() = Canceled or DeadlineExceeded14 case res := <-resultCh:15 return res.rows, res.err16 }17}
This is the exact pattern to use when you have a blocking operation that doesn't natively accept a context wrap it, put the work in a goroutine, select against ctx.Done(). One place. One select. The caller above it stays clean.
Context error types: what mid-level callers should care about
When a cancelled context propagates an error back up the chain, it's one of two types:
Untitled1import "errors"23func createOrder(ctx context.Context, p Payload) (*Order, error) {4 user, err := fetchUser(ctx, p.UserID)5 if err != nil {6 switch {7 case errors.Is(err, context.Canceled):8 // Client explicitly cancelled log at DEBUG, don't alert9 return nil, err10 case errors.Is(err, context.DeadlineExceeded):11 // Timeout hit log at WARN, this is worth tracking12 return nil, err13 default:14 // Real error log at ERROR, handle normally15 return nil, err16 }17 }18 // ...19}
context.Canceled means something upstream called cancel() a client disconnect, a load balancer kill, a parent handler returning early. Normal. Don't alert on it.
context.DeadlineExceeded means a timeout fired. This is worth tracking. If you're seeing it frequently on a specific path, your timeout budget is wrong or a downstream dependency is slow.
Most mid-level functions don't need this distinction they just return the error. But at the boundary where errors become logs, metrics, or HTTP responses, knowing which is which stops you from paging on client disconnects at 3am.
For goroutines wrapping non-context-aware operations, pass context explicitly and check it:
Untitled1go func(ctx context.Context) {2 select {3 case <-ctx.Done():4 return5 case result := <-doWork():6 process(result)7 }8}(ctx)
Don't close over the handler's context variable directly. Pass it as a parameter. Closures that reference outer variables can hold a reference to a context that's been cancelled by the time the goroutine runs or worse, a context that gets replaced in the outer scope.
The Part Most People Get Wrong
The most misunderstood case: a cancelled context does not abort work that has already started inside a goroutine unless that work is checking ctx.Done() or passing the context to something that does.
Consider this:
Untitled1func processOrder(ctx context.Context, orderID string) error {2 if err := validateOrder(ctx, orderID); err != nil {3 return err4 }5 // ctx cancelled here by client timeout6 return chargePayment(ctx, orderID) // still runs7}
If chargePayment calls http.Post without a context-aware client, the HTTP request goes out regardless of whether ctx is cancelled. Go's net/http package doesn't intercept in-progress writes when the context is cancelled. The request is already in flight.
The fix: use http.NewRequestWithContext(ctx, ...) and a client with no overriding timeout. The HTTP client will abort the request closing the connection when the context cancels.
Untitled1req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, body)2if err != nil {3 return err4}5resp, err := client.Do(req)
This seems obvious. It isn't, in a codebase where HTTP calls are wrapped in helpers that were written before context-awareness was standard.
Real-World Example
A logistics platform in Jakarta was seeing elevated database connection pool exhaustion during peak hours specifically during Lebaran, when order volumes spike roughly 4x. The symptom: pq: sorry, too many clients already errors, despite pool limits set conservatively.
The investigation found a handler that fetched route data, then dispatched a goroutine to log the request to an audit table. The goroutine used context.Background() because "audit logs shouldn't be cancelled by the user." Reasonable thinking. The problem was that the audit insert was slow the audit table had grown to 200M rows and wasn't being maintained and at 4x normal load, hundreds of goroutines were queued waiting for the insert to finish.
Each one held a database connection. The pool ran dry. Application requests started failing.
The fix was two parts. First, the audit log insert was moved to a buffered channel consumed by a dedicated worker pool with its own lifecycle context not derived from any request context, but cancellable on shutdown. Second, the worker pool size was capped, so slow inserts would drop audit events during overload rather than consuming connections indefinitely.
The context lesson: "this work shouldn't be cancelled by the user" doesn't mean "use context.Background()." It means use a dedicated context with its own lifetime typically derived from a service-level context that cancels on graceful shutdown. That's exactly what graceful shutdown wiring in Go is for.
FAQ
Q: Is it ever correct to use context.Background() inside a request handler?
A: Rarely. The legitimate case is when you want work to outlive the request and be managed by a separate lifecycle a background job, a cleanup task, something that belongs to the service, not the request. Even then, derive from a service-level context that cancels on shutdown, not from context.Background() directly. That way your service still shuts down cleanly.
Q: What happens if I ignore a cancelled context and finish the work anyway? A: The work completes, the result is discarded (nobody's listening), and you've consumed resources CPU, memory, DB connections, downstream API quota for nothing. At low traffic this is invisible. Under load it cascades: connection pools exhaust, downstream services get unnecessary traffic, timeouts compound. It's the kind of thing that causes a fine Tuesday to become a very bad Lebaran.
Q: How do I propagate context through code I don't control?
A: If the library doesn't accept a context, race it manually with select and ctx.Done(). If it's an HTTP call, use http.NewRequestWithContext. If it's a library you own, add the context parameter it's a one-way door, easier to add now than after a production incident. If it's truly external and unchangeable, document that the call is not cancellable and make sure callers know the goroutine will outlive the request.
Q: Does context cancellation work across gRPC service boundaries? A: Yes, if you're using Go's gRPC library correctly. gRPC propagates deadline and cancellation metadata across the wire automatically when you use the context from the incoming RPC as the parent for outgoing RPCs. The same rule applies: pass the incoming context, don't create a new root context mid-call.
Q: How do I find places in my codebase where context isn't being passed correctly?
A: go vet won't catch this. The most effective tool is staticcheck, which can flag functions that accept a context but where the caller passes context.Background() or context.TODO() in a handler context. Code review is the other lever make "does this function accept a context?" a standard review question for any PR that touches I/O.
Context propagation isn't an advanced topic it's table stakes for any Go service that handles real traffic. The teams that treat it as an afterthought are the same teams debugging connection pool exhaustion at 2am during a traffic spike.
Wiring it correctly from the start is the kind of decision that doesn't show up in performance benchmarks but shows up everywhere in production reliability.
Internal links used:
- Go Gotcha #1 goroutine leaks from missing context cancellation are the downstream effect
- graceful shutdown wiring in Go service-level context is the correct parent for background work
External links used:
- None all technical claims reference Go standard library and net/http documented behaviour
Word count: 1,820