Go context deadline exceeded: diagnose and fix timeouts

context deadline exceeded means that an operation's context reached its deadline before the caller observed completion. It identifies a time-budget outcome, not the underlying reason the operation was slow. A full connection pool, a waiting worker, a remote dependency and a response body that never finishes can all sit behind similar-looking messages.

This guide belongs to the 9 October archive edition and was researched and first published on 29 October 2026. It provides a diagnostic workflow and an original, standard-library lab. The examples use synthetic stages and transports rather than a production database or external gRPC service. The distinction matters: a reproducible local test establishes the behavior being tested, not the health of an unrelated deployment.

Start with three questions: which layer stopped waiting, what was the remaining budget, and what work still exists after that observation? Answering them usually leads to a better fix than increasing every timeout. The same questions apply to Gin handlers, background workers, SQL queries and RPC clients, even though each has its own error and lifecycle contracts.

For a local context error, use errors.Is rather than comparing the displayed string. Wrapping an error with %w lets the caller retain classification while adding the operation name. Our lab's Stage function checks an already-canceled context before starting, then waits for either an explicit event or cancellation.

select {
case <-gate:
    return nil
case <-ctx.Done():
    return fmt.Errorf("%s: %w", name, ctx.Err())
}

The complete source also performs the initial ctx.Err() check. That avoids starting work when cancellation is already known. It does not give cancellation magical priority over every simultaneous event. If completion and cancellation become ready together after the check, the operation needs a contract for the possible outcomes; select-case order is not a priority mechanism.

ctx.Err() distinguishes cancellation from deadline expiration. context.Cause can preserve a deliberately supplied application cause, such as a dependency-budget label. A child deadline cannot extend an earlier parent deadline, and calling a cancel function does not wait for the work to stop. These are central context contracts, which the lab tests separately.

An application cause is still not proof of a root cause. Naming a context “database budget” tells you which budget expired. It does not establish whether the database was executing, a connection was unavailable or the caller had already consumed most of its time elsewhere. Preserve that uncertainty in diagnostics.

Draw the operation as a sequence of owned stages: admission, queue wait, connection acquisition, remote execution, response consumption and cleanup. Record where each stage starts and ends. A timeout reported inside a query helper can originate from a parent request that spent most of its lifetime waiting before the helper was called.

Use stable operation names and approved numeric fields. Avoid dumping raw URLs, SQL parameters, authorization headers or capability links into logs. Our structured logging guide shows how to test a small event schema instead of treating every available object as diagnostic input.

For HTTP, the official tracing introduction describes hooks for events such as connection acquisition, DNS, dialing and response progress. A phase observation narrows the investigation; it does not independently prove why that phase took time. Callbacks may run concurrently, so any shared measurement state needs an ownership rule.

Suppose an operation has a chosen 240 ms total budget. In a synthetic serial example, admission consumes 70 ms, an HTTP dependency 80 ms, database work 40 ms and response work 20 ms. That leaves 30 ms of margin. These are teaching values, not a recommended production SLO or benchmark.

Creating a 200 ms child timeout after those first stages does not restore the original 240 ms. The child remains bounded by the parent's earlier deadline. Conversely, a smaller dependency budget can stop that dependency while the parent still has time to classify the failure and produce an appropriate response.

func Dependency(parent context.Context, budget time.Duration) (
    context.Context, context.CancelFunc,
) {
    return context.WithTimeoutCause(
        parent, budget, ErrDependencyBudget,
    )
}

The lab checks both cases. A child requesting an hour inherits a parent's ten-millisecond deadline. A three-second local budget can expire while an hour-long parent remains active. The tests use virtual time, so those chosen durations describe semantics without making the test suite wait for real hours.

Avoid treating every timeout value as a reservation that adds neatly across concurrent work. Parallel tasks overlap, queues consume time before service begins and response cleanup may have a separate owner. Write down which interval each limit covers, then verify the actual path. The objective is a coherent end-to-end contract, not a spreadsheet in which every helper appears to have plenty of time.

http.Client.Timeout covers connection establishment, redirects and reading the response body. Its timer continues after Do returns. A zero value means no overall client timeout; other configured limits may still apply. The Client reference defines that scope.

Our test supplies a custom transport that waits for the request context to end, without making a network connection. The caller has an hour-long context, but the client has a two-second timeout. The call returns a deadline-classified error while the original caller context remains active. This demonstrates why checking only the original ctx.Err() can miss which layer stopped the HTTP operation.

In a real service, inspect the complete configured path: request context, client timeout, transport limits and any proxy or load-balancer budget. Do not assume that equal-looking error messages identify the same timer. A response-header limit is not the same interval as an overall client limit, and a connection limit is not an application transaction limit.

Always handle the response body according to its owner. A successful status or returned response does not mean the body was completely read. Our HTTP connection guide and bounded I/O guide explain related cleanup and framing decisions. Increasing a timeout cannot repair code that waits for an impossible framing condition.

A SQL operation can wait for a usable connection before the database executes the statement. Under load, a small pool, long transactions or retained rows can consume that capacity. The error seen by the request owner may therefore describe an exhausted caller budget rather than a slow statement alone.

Pass the appropriate context to context-aware database methods and release the derived cancel function when its work is finished. The official database cancellation guide demonstrates this pattern. The actual interruption behavior also depends on the driver and database; a context value cannot guarantee that an arbitrary implementation stops an external effect immediately.

Compare pool statistics with database-side execution evidence. Investigate retained rows and transaction duration before increasing the connection maximum. More connections can move the queue into the database, increasing contention without improving completed work. Our SQL pool and transaction guide develops that capacity boundary.

For writes, distinguish the caller's observation from the durable outcome. A lost connection or deadline during a commit path may leave uncertainty that needs operation-specific recovery. Do not state that every timed-out write rolled back unless the actual database protocol and observed result establish it. A retry policy must respect that uncertainty.

gRPC has its own status classification. Inspect a returned RPC error using the status API, for example status.Code(err) == codes.DeadlineExceeded, rather than assuming every remote status is a directly wrapped local context sentinel. That expression requires the gRPC Go packages; it is not part of the dependency-free lab.

The gRPC deadline guide explains propagation and notes that the server application must stop work it spawned. Go supports deadline propagation when the relevant incoming context is used for outgoing calls. Replacing it with a fresh background context discards the original cancellation relationship instead of repairing a slow dependency.

The status-code definition explicitly allows DeadlineExceeded even when a state-changing operation completed and its reply arrived too late. Therefore, a retry after this status is a business decision. Determine whether the logical operation has an identity, whether its result can be queried and whether repeating it can duplicate an effect.

For streams, define what happens after partially consumed output. Retrying from the beginning can repeat messages already delivered to the consumer. Practice the gRPC stream interview scenario and use the idempotency guide to reason about the effect, not only the transport status.

A goroutine may need to release resources after it observes cancellation. Calling cancel() alone does not prove that cleanup finished, a lock was released or a dependent worker exited. The owner needs an observable completion path, such as receiving from a result channel after the work and cleanup are done.

Our Launch helper models this deliberately. Its worker first waits for a stage result, then waits on a controlled cleanup gate, then reports completion. The test cancels the context and waits until the goroutines settle. It verifies that the completion channel is still unavailable while cleanup is held, then releases cleanup and receives the cancellation-classified result.

The cleanup gate is a test device, not a production cleanup implementation. Its purpose is to make the distinction observable without scheduler guesses. A real owner must choose how cleanup finishes and what limit applies if cleanup itself can block. A one-element result channel prevents the example worker from being stuck solely because the owner has not received the result yet; it does not replace that owner's responsibility to observe completion.

This relates to context contracts and graceful shutdown. A system that stops accepting new work but never joins accepted work has not finished shutting down merely because every cancel function was called.

Replacing an expired request context with context.Background() or context.WithoutCancel can make the symptom disappear from a helper while leaving work alive beyond the caller that created it. That may be appropriate only when the application explicitly transfers ownership, admission limits, permissions, persistence and shutdown responsibility to another component.

If a request should create a durable background job, give that job a deliberate acceptance contract and a durable owner. Decide when the request can truthfully say the job was accepted, how progress is recovered and what happens on process failure. Detaching a context supplies none of those guarantees by itself.

For request-scoped work, preserve cancellation and fix the actual waiting or budget problem. For independently owned work, use the owner's lifecycle and a finite operation budget. Do not retain a pooled Gin request context in a background goroutine. The Gin worker lesson and WithoutCancel interview guide explain these ownership boundaries.

A useful review question is simple: if the original caller disappears now, which component can still explain, stop and recover the work? If the answer is “the goroutine probably finishes,” the design is missing an owner rather than a timeout constant.

Download the original hiring research and context lab. The Go module declares 1.25; our recorded compiler is Go 1.27.3 on darwin/arm64. The lab uses the standard library, synthetic channels and custom HTTP transports. It opens no network listener and does not contact the illustrative .invalid address.

go test -race -count=50 ./...
go vet ./...
go run ./contextlab

The tests cover an earlier parent deadline, local expiration with a named cause, cancellation before cleanup completion, already-canceled work, a client timeout with an active caller context and an immediate synthetic HTTP success. The native program prints separate deadline-identity, cause and joined-worker observations. It does not benchmark a database or run an external RPC.

testing/synctest provides a virtual clock inside its bubble and advances time when the relevant goroutines are durably blocked. Real socket I/O is outside that mechanism, which is why the HTTP tests use controlled transports. Read the synctest reference and our controlled concurrency guide before substituting a real server into a virtual-time test.

The suite passed fifty race-detector runs and vet. Temporary broken variants must fail the intended tests, including lost parent propagation, incorrect cancellation identity, discarded error wrapping and completion before cleanup. The standalone program also cross-compiles for wasip1/wasm; successful target compilation does not certify execution in every host.

Save your current Playground draft, then copy the complete contextlab/main.go with a compatible module. Editing does not run Go. If collaborating, deliberately create a temporary room and press Run on the selected compatible native device; the relay shares source and device-attributed output. The MCP guide describes the execution boundary and temporary-link behavior.

Change one assumption at a time. Start with an already-expired deadline, then compare explicit cancellation. Observe the named cause separately from the standard error identity. In a native test environment, adjust the local child budget and confirm that it cannot extend the parent. Keep the assertions about meaning, not the exact wording of a message.

For an interview or portfolio review, explain the sequence before showing code: where the budget begins, who may shorten it, which layer reports expiration and who joins the remaining work. This connects the Go job preparation guide to an inspectable engineering artifact. It is more useful than claiming “production-ready timeouts” without a failure test.

If waiting consumed the budget, inspect admission and capacity. If a remote dependency is genuinely slow, inspect its own evidence and decide whether the operation needs a different service contract. If an effect may have completed, reconcile before repeating it. If work outlives its owner, fix cancellation and completion ownership.

A longer timeout can be an intentional product decision when the operation is allowed to take longer and the system can sustain that work. It should not be a substitute for understanding the queue or hiding a leak. Recheck completed work, retained resources and failure outcomes after changing the policy.

The useful result is not the disappearance of one error string. It is a system in which the caller's budget, dependency behavior, operation outcome and worker lifecycle agree with a contract you can explain and test.