Goroutine Leaks: Who Stops This Thing

Starting a goroutine takes two characters. Stopping one takes a plan, and the language provides no default.

There is no kill, no interrupt, and no timeout on a goroutine. A goroutine ends exactly one way: its function returns. Everything else is a mechanism for persuading it to return.

That asymmetry is deliberate. Killing a thread from outside is unsafe in every language that has tried it, because the victim may hold a lock, be mid-write, or own a resource nobody else can release. Go declined to offer it.

The consequence is a question with no default answer, and it must be answered for every goroutine you start: what makes this return?

If the answer is that it finishes its work, fine. If the answer is that it loops until something tells it to stop, then something must be able to tell it, and building that channel is your job.

A goroutine with no answer is a leak waiting for the right input.

A leaked goroutine is not merely idle. It is blocked forever on a channel operation, and three things follow.

It is never garbage collected. A blocked goroutine is a live root, so its stack and everything reachable from it stay allocated. Leak one holding a large buffer per request and memory grows with traffic.

It holds resources. Open connections, file handles, and mutex guards it happens to be carrying are never released.

It is silent. Nothing errors, nothing logs, and the program keeps serving. The symptom is memory growth and eventual failure hours later, with a stack trace pointing at whatever allocated last rather than at the cause.

That third property is what makes it the characteristic Go bug. A deadlock announces itself when the whole program stops; a leak announces itself as a gradual, unexplained resource climb that looks like a memory leak in the ordinary sense and is not.

The scale multiplies it. Leak one goroutine per request at a thousand requests a second and there are 3.6 million by the end of the hour.

The canonical case appears in code that looks entirely reasonable.

func first(urls []string) string {
    ch := make(chan string)          // UNBUFFERED
    for _, u := range urls {
        go func(u string) {
            ch <- fetch(u)           // blocks until someone receives
        }(u)
    }
    return <-ch                      // take the first, return
}

The intent is a race: start several fetches and return whichever finishes first. It works, and it leaks every goroutine but one.

The channel is unbuffered, so each send blocks until a receiver takes it. Exactly one receive happens, then the function returns. The remaining goroutines are blocked on their sends forever, and nothing will ever receive because the only receiver has gone.

Call this with five URLs a thousand times and four thousand goroutines are stuck, each holding its response.

The one-character fix is to buffer the channel to the number of senders:

ch := make(chan string, len(urls))   // every send succeeds immediately

Now each goroutine sends into the buffer and returns. The unread values become garbage once the channel is unreachable, which is fine: the goroutines finished, and finishing is what matters.

Four shapes account for essentially every leak, and each has a standard remedy.

The recurring theme is a missing partner. A channel operation needs a counterpart, and the leak is the case where the counterpart went away, was never created, or exited by an error path nobody considered.

That last one deserves emphasis. Most leaks are on error paths. The happy path was tested, drains the channel, and closes it properly. The path where a request fails halfway returns early, and the goroutine started at the top is still waiting to hand over its result.

The practical consequence is that leaks are found by asking, for every early return, whether anything was left waiting.

The general defence is to make every blocking operation cancellable, so that no goroutine is ever waiting on a single thing with no alternative. That is what the next step is about.

The standard mechanism is context.Context, and its core is one channel.

A context carries a Done() channel that is closed when the work should stop. Closing is the ideal signal here: it never blocks, it can be observed by any number of goroutines at once, and it cannot be un-signalled.

func worker(ctx context.Context, in <-chan Job) error {
    for {
        select {
        case job, ok := <-in:
            if !ok { return nil }
            process(job)
        case <-ctx.Done():
            return ctx.Err()          // cancelled or timed out
        }
    }
}

Every blocking operation now has an escape. The goroutine waits for work or for cancellation, so it can always return.

Contexts form a tree. Deriving a child context with a timeout or a cancel function means cancelling a parent cancels every descendant, so one cancellation at the top of a request unwinds every goroutine it spawned, however deep.

That is the mechanism behind the convention of passing ctx as the first parameter of anything that blocks. It looks like ceremony and it is the cancellation path: a function without a context cannot be told to stop, and neither can anything it starts.

Four rules eliminate most leaks, and they are about ownership rather than cleverness.

Whoever starts a goroutine is responsible for it stopping. Not the goroutine, not the caller: the code containing the go statement. If you cannot state what makes it return, do not start it.

Every blocking operation gets a cancellation case. A bare <-ch in long-lived code is a latent leak; a select with ctx.Done() is not.

Always call cancel. Deriving a cancellable context returns a cancel function, and defer cancel() releases the resources associated with it even on the happy path. Failing to is itself a leak, and go vet checks for it.

Close from the sender, on every path. Including error paths, which is what defer close(ch) at the top of the sending goroutine achieves.

A fifth is worth adding for libraries: a function that starts a goroutine should say so, and either return something that waits for it or take a context. A library quietly starting a background goroutine the caller cannot stop is a leak the caller cannot fix.

Leaks are easier to detect than most bugs, because the evidence is a number that only goes up.

Watch the count. runtime.NumGoroutine() returns how many exist. Exporting it as a metric turns leaks into a visible trend: a healthy service returns to a baseline between bursts, and a leaking one climbs monotonically.

Take a goroutine profile. The runtime can dump every goroutine's stack, showing exactly where each is blocked. A leak appears unmistakably: ten thousand goroutines stopped at the same line. This is the fastest route from symptom to cause in production.

Test for it. Record the count at the start of a test, run the code, allow a moment for shutdown, and assert the count returned to its baseline. Leak-checking libraries automate this, and it catches leaks at the commit that introduces them rather than in production.

Read every early return. In review, the question is whether anything was left waiting when this path fires, which is where the leaks that survive testing live.

The first two are the significant ones. A goroutine count on a dashboard converts a class of silent, delayed failures into an obvious upward line.

Every row is the same question in a different costume: what makes this goroutine return, on every path including the ones that fail?

That question is the whole lesson. Go makes starting concurrent work so cheap that the starting is invisible, and the stopping is the part that needs deliberate design. Nothing in the language forces you to think about it, and the failure is silent, delayed, and far from its cause.

The compensating strength is that the fix is mechanical once the discipline is in place: contexts everywhere, cancellation cases in every select, closes owned by senders, and a goroutine count on a dashboard.

What remains is why the language looks the way it does at all, which is the last lesson.