Go 1.27 goroutine leak profiles: find the owner, repair the exit

On 2 September 2026, the Go team explained the goroutine leak profiler available in Go 1.27. The goroutineleak profile can identify certain goroutines that are permanently blocked on Go synchronization primitives. It is available through runtime/pprof and, when those handlers are installed, through /debug/pprof/goroutineleak. The feature was previously experimental; the Go 1.27 release makes it generally available.

The important qualification is its scope. The profiler does not establish that an application has no leaks simply because a capture is empty. The official article describes reachability-based detection and its limitations. Our practical focus is the work that follows a useful capture: identifying ownership, repairing an exit path and proving that the relevant workers finish. That process matters for services, command-line tools and background processing alike. A new diagnostic can point to a stack; the application still needs a design that explains who started the worker, who can stop it and who observes its completion.

A server normally contains goroutines that wait. A worker may be ready for its next task, a connection reader may be idle, and a coordinator may be waiting for another operation to complete. A high count of waiting goroutines is therefore a question to investigate, not a diagnosis by itself. The lifecycle and workload provide the context.

Imagine a service that starts several workers for each imported file. The coordinator returns early when one worker reports an invalid record. The remaining workers still try to deliver their results, but nobody receives them. The interesting fact is not merely that the workers are blocked. It is that the operation which owned the receive side has finished without arranging a way for those workers to leave.

Draw the operation from start to finish, including the failure path. Name the coordinator, input producer, workers and result consumer. For each channel, identify who sends, who receives and who owns closure. Then ask what changes when a caller cancels, a parser rejects an input or the downstream system stops accepting results. This map turns an intimidating collection of stack traces into a small set of ownership questions. The concurrency course unit is a useful foundation for that exercise.

If the application already has an approved diagnostic interface, use that established path. Keep profile collection on a controlled administrative endpoint rather than adding a public diagnostic route to the main application just for convenience. Profiles and stack traces can reveal implementation details, so the access decision belongs with the service’s operational controls.

For a local development process with the handlers deliberately installed on a loopback listener, the capture can be as simple as:

curl --fail http://127.0.0.1:6060/debug/pprof/goroutineleak -o leak.pprof
go tool pprof -top ./service leak.pprof

Use the executable that corresponds to the running process when interpreting source locations. Record the process version, capture time and workload that led to the suspected leak. These commands illustrate collection from an endpoint you control; they do not create that endpoint or configure production access for you.

The pprof package reference explains profile types and output. A capture becomes much more useful when it is attached to a reproducible scenario. “Import one invalid file, cancel the operation, then capture” is an actionable description. “The process looked large after a busy day” is a starting observation, but it leaves much more work before the team can identify a specific failed lifecycle.

A reported blocked send identifies where a worker is waiting. It may not identify the function that made the worker impossible to complete. In the file-import example, the defect can live in the coordinator’s early return rather than in the line that sends the result. Review both sides of the channel before changing a buffer size or adding a cancellation case.

Trace the worker back to the operation that created it. What promise did that operation make about completion? Does it wait for children before returning? Does it signal cancellation on every exit path? Can a caller abandon the result without notifying the producer? These are design questions that a profile cannot answer on its own.

Keep the original capture and write a small narrative beside the proposed fix. For example: “The consumer returns after the first invalid record. Producers can still attempt one send each. The parent must cancel remaining work and wait for its workers before ending the import.” That explanation is stronger than “added context to fix a leak” because it identifies the broken obligation. Our architecture interview guides help practice explaining boundaries in these terms. A goroutine lifecycle is an ownership boundary just as much as a database transaction or an HTTP response body.

Passing a context into a function does nothing unless the function uses it at the points where it may need to stop. A worker can observe cancellation while waiting for input and still become stuck later while sending output. Review the full path, especially the transition between receiving a value, doing work and delivering the result.

This fragment forwards integers while allowing its owner to cancel either wait. It deliberately leaves output-channel closure to the coordinator, which may have more than one producer.

func forward(ctx context.Context, in <-chan int, out chan<- int) {
    for {
        select {
        case <-ctx.Done():
            return
        case value, ok := <-in:
            if !ok {
                return
            }
            select {
            case out <- value:
            case <-ctx.Done():
                return
            }
        }
    }
}

The fragment is not a complete worker-pool implementation. Its caller must still define the lifetime of the context, the channel owners and the join operation. If processing a value itself can block, that processing needs an appropriate cancellation or deadline contract as well. The context documentation defines the signaling mechanism; the application supplies the lifecycle that makes the signal meaningful. Keep those responsibilities visible in the interface instead of relying on a convention buried inside a helper.

Cancellation is a request. Completion is an observation. A coordinator that calls a cancel function and immediately discards every reference to its children may still return while those children are running. Decide where the operation waits for them and what happens if a dependency cannot finish within the required shutdown budget.

For the import service, separate the signal from the join in the design. The coordinator owns the cancellation function and a mechanism for observing worker completion. On a validation failure, it stops accepting new work, signals the remaining workers and waits for the owned group to exit before releasing operation-specific resources. The exact join mechanism can vary; the ownership obligation should not.

Write down the closure rule as well. A consumer should not close a shared result channel while producers may still send to it. A coordinator that knows all producers have exited can safely perform the closure it owns. This is why a quick “close the channel on error” patch can turn one concurrency defect into another. The sync package reference documents common synchronization tools, but it does not choose the application’s owner. Review the lifecycle first, then select the smallest mechanism that expresses it clearly.

A useful test does more than sleep briefly and inspect a count. It should trigger the failure or cancellation path and observe that the specific workers owned by the operation finish. Use channels, joins or other explicit synchronization to establish the events the test depends on. Keep a bounded failure timeout so a regression fails the test instead of hanging the entire suite.

For the forwarding example, test cancellation while no input arrives, input closure and delivery to a receiver. Add a case where the receiver stops consuming and the owner cancels the operation. Verify the completion signal rather than assuming that a cancel call proves the worker exited. These cases exercise different obligations even though they share a small function.

Run the relevant tests under the race detector when supported by the target and build configuration. Remember that race detection and leak detection answer different questions. A program can be race-free and still wait forever. The Go race-detector guide explains its purpose, while the testing reference covers the test framework. Combining tools is useful when each result is interpreted narrowly. The goal is a reproducible lifecycle check, not a collection of green tools whose guarantees are overstated.

The new profiler cannot identify every possible form of abandoned work. Reachable synchronization objects can prevent the runtime from proving that a waiter will never be released. Network or file I/O and custom synchronization also need their own investigation. An empty capture therefore leaves meaningful questions about operation budgets, ownership and the behavior of external dependencies.

In the import service, a worker may wait indefinitely for a remote storage call even after channel handling is correct. That is a different boundary from the blocked result send. Check the client’s cancellation behavior and verify it through a controlled failure scenario. The HTTP connection-reuse analysis discusses the neighboring problem of owning a network response and its deadline.

Use ordinary goroutine profiles, application metrics and focused tests alongside the leak-specific profile. A persistent rise after repeated completed operations can still deserve investigation even when the runtime cannot classify those goroutines as leaked. Treat each diagnostic as a lens with a defined field of view. The team’s confidence should come from several compatible observations and a readable lifecycle argument, not from the absence of one particular kind of report.

When a suspected leak appears under real traffic, start with a controlled collection plan. Identify the process version and the operation of interest, collect through the existing administrative path and retain the evidence with the incident record. Avoid repeatedly forcing expensive diagnostics without understanding the service’s capacity and the tool’s cost on the actual workload.

Compare the capture with the operation’s completion metrics and the timing of failures. Then build the smallest development scenario that reproduces the ownership problem. A production symptom can be complicated, but a good regression test usually focuses on one broken promise: a parent returns while a child remains unable to finish.

After the fix, verify both recovery and steady operation. Confirm that new operations no longer accumulate the affected workers, and decide whether already stuck workers require a process restart through the normal operational procedure. Do not assume that a source change retroactively repairs every existing execution. Record the deployed artifact and observation window. Our release-evidence analysis explains why linking source, candidate and running process is essential when interpreting any before-and-after diagnostic result.

For every goroutine introduced by a change, ask four questions: who starts it, what can block it, how can it stop and who observes that it has stopped? Apply the questions to the failure path as carefully as the happy path. Add the corresponding test before calling the lifecycle complete.

For interview preparation, explain why adding a buffer can solve one finite producer scenario without being a universal leak fix. Then describe a case where cancellation is observed before a receive but forgotten before a send. Finally, explain why a clean race-detector run and an empty leak profile still do not prove that every operation has a bounded lifetime. The concurrency interview topic is a useful route for working through those distinctions.

Go 1.27 gives engineers a sharper way to locate some permanently blocked workers. The feature becomes most valuable when the resulting stack trace leads to a clear ownership repair and an observable shutdown test. Keep the capture, fix the obligation and verify the exit. Every worker should have an owner who can explain how it gets home.