Find the owner and the lifetime#
Files, connections, locks, goroutines and subscriptions each have one owner that should release them. Ask three questions:
- Who created it, and who is supposed to release it? A framework's session, a pooled connection or a shared client usually belongs to the code that made it.
- What is the longest the owner can live? A command-line run, a request, a test, a long-running server and a config entry reloaded many times give the same leak very different costs.
- Is there a path where release does not happen? Look for early returns, panics, cancelled contexts and sends on channels that nobody will read.
A goroutine ends only when its function returns, so one blocked forever on a channel send keeps its stack and everything it references. The language specification says when a send blocks: on an unbuffered channel until a receiver is ready, and on a buffered one while the buffer is full.
A comment that found a broken invariant#
In October 2026, a pull request to Genkit's Go SDK made a panic in a tool call fail the call rather than crash the process. Each tool call runs in its own goroutine and sends one result on resultChan, which is buffered with one slot per tool request. The reviewed version recovered the panic in a deferred function that sent a second result, and carried a comment saying that the panic "cannot follow a send on resultChan, which is the last thing every path does."
gemini-code-assist's review summary disagreed: "The review feedback highlights a critical issue in handleToolRequests where a panic in a deferred function could trigger a double-send to resultChan, potentially causing a goroutine leak." It added: "It is recommended to refactor this block to use a single deferred send pattern." Review
The reviewed code bears the bot out. The same goroutine also ran defer sink.Close(), and deferred calls run after the function body, so a panic there would follow the normal send. A second send breaks the rule the buffer was sized for, though it does not always leak. The receiving loop stops at one result per request or at the first error, so a goroutine stays blocked only when the loop stops early with more extra sends pending than results read. A small Go simulation with three calls, one failing normally, left no goroutine stuck after one double send and one stuck after two. The leak needs several failures in one round, but the code's comment said it could not happen.
The author changed the design. Commit 3057c80, "fix(go/ai): send each tool result exactly once", says: "A tool goroutine now records its outcome and sends it from one deferred function," "so a panic in a later deferred call (sink.Close) overrides the outcome instead of sending a second result." Pull request The merged code sends through defer func() { resultChan <- res }(), which restores the invariant that an existing comment on the error path relies on: a sibling goroutine still running after the function returns is not leaked, because "its send cannot block: resultChan buffers one slot per request." Merged file The pull request merged on 10 October 2026.
A correct comment about a short-lived leak#
Four days later, gemini-code-assist said a test change in Google Cloud's Scion repository leaks a goroutine "due to how PTYClient handles stdin reading." It explained that after the test closes its stdin pipe, the reader goroutine gets an error and "attempts to send this error to ch via ch <- stdinResult{nil, err}," and that "because ch is an unbuffered channel and pumpStdin has already exited, there are no active readers for ch." It proposed a select on c.ctx.Done() in startStdinReader. Review comment
Nobody replied, and the pull request merged on 22 October 2026 without that change. startStdinReader in pkg/wsclient/pty.go still uses an unbuffered channel and a plain send on the current main branch.
The mechanism is right. A short Go program in which a goroutine sends a read error on an unbuffered channel after its consumer has returned left one goroutine behind according to runtime.NumGoroutine. With the bot's select on a cancelled context, it left none.
The cost depends on lifetime, which the comment did not weigh: AttachToAgent reads the process's os.Stdin, and in an interactive command stdin stays open while the process runs, so the goroutine sits in Read until the process exits. The leak appears only where stdin closes first, here the test binary, at one goroutine per run. That makes the comment a fair follow-up issue for code outside the diff, not a reason to block a test-output fix. This check covered the reader and its caller, not other callers that might run the client in a long-lived process.
Decide from ownership and lifetime#
| What you find | Response |
|---|---|
| The code under review owns the resource and a reachable path skips release | Change: release on every path, with defer, with, try/finally or a single exit |
| The resource belongs to a framework, pool or caller that releases it | Dismiss, naming the owner, such as a shared HTTP session the framework closes |
| The leak is real but bounded by a short lifetime, such as a CLI run or a test | Defer to an issue or fix it if it is small; say which lifetime bounds it |
| The leak grows with something unbounded: requests, reloads, reconnects | Change, and add a test that repeats the operation |
| You cannot tell whether release happens | Write a test that counts handles or goroutines before and after |
For the last row, in Go, Uber's goleak fails a test that leaves goroutines running. In Python, running tests with warnings enabled surfaces the ResourceWarning that an unclosed file or socket emits when it is collected. When the owner is a framework object that is reloaded, such as a connection pool per configuration, the connection limits guide shows how a slow leak turns into refused connections.