Go

Finding a Leaked Goroutine with Go 1.27's goroutineleak Profile

A goroutine that blocks on a channel receive and can never be unblocked does not exit. It holds its stack and its scheduler slot for the rest of the process, and a server that leaks one per request grows until it restarts. Go 1.27 made a profile for exactly this case generally available: the goroutineleak profile in runtime/pprof reports only the goroutines that cannot possibly become unblocked. This guide writes a one-goroutine leak, captures the profile, and reads it with go tool pprof. The report names 1 leaked goroutine, parked in runtime.gopark via a channel receive, created by the anonymous function in main. The guide then fixes the leak by closing the channel, and the same profile on the fixed program reports 0 leaked goroutines.

Written November 11, 2026 · Tested with Go 1.27 · 9 min read

By the end of this guide
  • The leak, written on purpose
  • Capturing the profile
  • Reading the profile with go tool pprof
  • The fix: close the channel

What this guide is

A leaked goroutine is a goroutine that is blocked on a concurrency primitive, such as a channel, a mutex, or a condition variable, and cannot possibly become unblocked again. That wording is the Go 1.27 release notes wording, and it matters: a goroutine that is merely waiting for work that will arrive is not leaked, while a goroutine waiting on a receive from a channel that nobody will ever send on or close is leaked. Before Go 1.27, finding one meant reading the full goroutine profile and judging every stack by hand. The goroutineleak profile does the judging step: it reports only the goroutines that match the leak definition. This guide runs three programs: the leak itself, the same program with the channel closed, and a comparison that writes both the regular goroutine profile and the leak profile for one blocked goroutine.

The leak, written on purpose

The smallest leak is one goroutine and one channel. The goroutine receives from the channel, nobody sends on the channel, and nobody closes it, so the receive never returns:

Go
package main

import (
    "fmt"
    "os"
    "runtime/pprof"
    "time"
)

func main() {
    ch := make(chan int)
    go func() { <-ch }()
    time.Sleep(100 * time.Millisecond)
    p := pprof.Lookup("goroutineleak")
    if p == nil {
        fmt.Println("NO goroutineleak profile")
        os.Exit(2)
    }
    f, _ := os.Create("goroutineleak.prof")
    p.WriteTo(f, 0)
    f.Close()
    fmt.Println("goroutineleak profile written")
}

The program sleeps for 100 milliseconds so the goroutine has time to block on the receive, then looks up the leak profile, writes it to a file, and prints one line. The exact output of the run:

Output
goroutineleak profile written

The print statement proves the lookup found the profile and the file was written. It says nothing about what the profile contains, which is the next section's job. One detail in the code is load-bearing in real programs: the lookup result is checked before use. The runtime/pprof package documents that a lookup by name returns nil when no profile with that name exists, so code that asks for a profile by a string name must handle the missing case instead of writing through a nil profile.

Capturing the profile

The capture has three steps, and each one is in the program above. First, pprof.Lookup("goroutineleak") returns the profile object for the leak profile. Second, the result is checked against nil, because a profile name is a string and a misspelled or unavailable name is a runtime condition, not a compile error. Third, WriteTo writes the profile to an open file, and the second argument, 0, selects the binary profile format that go tool pprof reads. A server does not need the file form: the Go 1.27 release notes state that the same profile is also available as the net/http/pprof endpoint /debug/pprof/goroutineleak, so a running server that already serves the pprof endpoints can hand the leak profile to the same tool over HTTP. The file form is what this guide uses, because the leak here is a short-lived test program rather than a server.

A note on versions, because the profile is new. The release notes state that the goroutineleak profile was previously available as an experiment in Go 1.26 and is generally available in Go 1.27, and that the experiment setting for it is deleted in Go 1.27. This box carries both toolchains, and the same leak program was also built and run with Go 1.26.4 under GOEXPERIMENT=goroutineleakprofile: it printed the same line and wrote a profile. Without that experiment flag, a Go 1.26.4 build finds no such profile — the lookup returns nil and the program above exits 2. So the profile answers on both versions, but on 1.26 only in an experiment build. The nil check still belongs in the code, because the lookup contract allows nil for a name that a given runtime does not define, and the cost of the check is one comparison.

Reading the profile with go tool pprof

The profile file is binary, so the reading tool is go tool pprof. The -top form lists the functions the leaked goroutines are parked in, with flat and cumulative counts:

Command
go tool pprof -top ./leak goroutineleak.prof

The table:

Output
Showing nodes accounting for 1, 100% of 1 total
      flat  flat%   sum%        cum   cum%
         1   100%   100%          1   100%  runtime.gopark
         0     0%   100%          1   100%  main.main.func1
         0     0%   100%          1   100%  runtime.chanrecv
         0     0%   100%          1   100%  runtime.chanrecv1

Read the table from the total down. The header line says the profile accounts for 1 goroutine in total, so this program leaks exactly one. The one flat count sits on runtime.gopark, which is the runtime function a goroutine parks in when it blocks. The cumulative chain names the path: runtime.chanrecv and runtime.chanrecv1 are the channel receive, and main.main.func1 is the anonymous function that main started with the go statement. In a real program that last name is the finding, because it points at the code that created the goroutine: the creator is where the missing send, the missing close, or the missing cancellation lives. Flat counts answer where goroutines are parked; the cumulative chain answers how they got there.

The fix: close the channel

A receive from a closed channel returns at once, with the zero value, so closing the channel is the smallest fix for this leak. The fixed program is the leak program with one line added after the go statement: close(ch). The goroutine's receive returns, the function ends, and the goroutine exits before the profile is taken. The fixed program prints fixed profile written, exits with code 0, and writes a 188-byte profile. Reading that profile with the same command gives a different header:

Output
Showing nodes accounting for 0, 0% of 0 total

Zero total is the proof shape to look for: the profile was captured and read the same way as the leak's profile, and it contains no leaked goroutines. Closing is the right fix when one sender side owns the channel and no further values will arrive. When several goroutines wait and the signal means stop working rather than no more values, the same shape applies with a dedicated done channel that the owner closes once, or with a context that the owner cancels; in both forms the point is identical, namely that some named owner is responsible for unblocking every waiter. A leak is usually not a goroutine that forgot to exit. It is a channel or a signal whose owner never performs the unblocking step.

Trap: the regular goroutine profile counts more than leaks

Trap
The older goroutine profile reports every goroutine in the process, including the ones doing healthy work and the one taking the profile. A third program starts the same single blocked goroutine and writes both profiles. Its goroutine profile reads:
Output
Showing nodes accounting for 2, 100% of 2 total

Two is correct for that profile and misleading as a leak count: one node is the blocked goroutine, and the other is the main goroutine caught in the act of writing the profile, parked in runtime.gopark under the profile writer itself. The same program's goroutineleak profile reports 1 total. So the two profiles answer different questions. The regular profile answers what is running and where; the leak profile answers which goroutines cannot become unblocked. Reaching for the regular profile to count leaks counts too many by construction, and the excess grows with the size of the program, because every healthy blocked waiter appears in it too.

There is a second limit in the other direction, stated in the Go 1.27 release notes: the leak profile does not detect every possible leak, and the notes name leaks caused by blocking on concurrency primitives that stay reachable through global variables or through the local variables of runnable goroutines. A clean leak profile is strong evidence, not a proof that no leak exists. If a process keeps growing while its leak profile reads zero, the regular goroutine profile, read over time, is the next instrument.

Key result
for one blocked goroutine, the regular goroutine profile reports 2 total while the goroutineleak profile reports 1; and a zero leak profile does not rule out the reachable-variable leak class the release notes exclude.

When to reach for which profile

Question Profile Why
Which goroutines can never become unblocked goroutineleak It reports only goroutines blocked on a primitive they cannot be released from
What is every goroutine doing right now goroutine It lists all goroutines, including healthy waiters and the profiler itself
Did the fix work goroutineleak, taken the same way after the fix The total drops to 0 when no goroutine matches the leak definition
The leak profile is clean but the process still grows goroutine, compared across two captures Leaks outside the leak profile's stated scope still appear as accumulating stacks

The order used in practice: take the leak profile first, fix what its creator chain names, and retake it to confirm the total fell. Keep the regular profile for the cases the leak profile does not claim to cover.

Checklist

  • Before blaming a goroutine count, take the leak profile: a total above 0 names creator chains to fix.
  • Before using a profile returned by pprof.Lookup, check it against nil: a name that a runtime does not define returns nil.
  • Before reading a total as a leak count, confirm which profile produced it: the regular goroutine profile includes healthy goroutines and the profiler itself.
  • Before declaring a fix, retake the leak profile the same way: the fixed program's total is 0.
  • Before closing a channel as the fix, confirm one owner and no further sends: a send on a closed channel panics, so the close belongs to the sending side.
  • Before trusting a clean leak profile as final, remember its stated scope: leaks through primitives reachable from globals or runnable goroutines are outside it.

Sources

  • Go 1.27 Release Notes — the goroutine leak profile section: generally available in Go 1.27, an experiment in Go 1.26, the leak definition, the stated detection limits, and the HTTP endpoint.
  • runtime/pprof package documentation — the profile lookup by name, the nil result for an undefined name, and the goroutineleak entry in the profile list.
  • Go Blog, Profiling Go Programs — how to read pprof output, including the flat and cumulative columns.

Keep Exploring