goroutine-leak-check
Use when adding/changing concurrent Go (goroutines, channels, worker fan-out, context cancellation) or when asked to find/verify/fix goroutine leaks — instruments tests with uber-go/goleak (and the Go
SKILL.md.claude/skills/goroutine-leak-check/SKILL.md
GitHubGoroutine-leak verification & repair
UnPixel's hot path fans out across goroutines (offset discovery, intra-node DFS,
per-font sweeps, blind/mosaictext decoders) and streams a Progress channel. A leaked
goroutine — one blocked forever on a channel send/receive or a lock no runnable
goroutine can release — is a real correctness and memory bug. This skill verifies there
are none, and fixes any it finds.
State of the art (2026): uber-go/goleak at test
boundaries (the portable default), and Go 1.26's experimental goroutineleak pprof
profile (GC-based, no false positives — it reports only goroutines it can prove are
stuck). This project is on Go 1.26, so both are available.
Checklist (create a todo per item)
- Instrument the concurrent packages with goleak at the test boundary.
- Run the caged suite and collect every leak goleak reports.
- Diagnose each leak against the known patterns below (real leak vs. test artifact).
- Fix the production code (not the test) for real leaks; suppress only proven framework goroutines, narrowly and with a reason.
- Re-run caged until clean; confirm the panel is 17/17.
- Keep the gate:
mise run leak. Because the per-packageTestMainactivates goleak on everygo testrun,mise run testandmise run ci(viatest:ci) already detect leaks for free —mise run leakis the explicit, thorough caged run.
1. Instrument with goleak
Add the dependency (pure Go, no CGO — allowed):
go get go.uber.org/goleak
For each package that starts goroutines, add one TestMain so the check runs after
the whole package's tests (this is compatible with t.Parallel, unlike a per-test
defer goleak.VerifyNone(t)):
package search
import (
"testing"
"go.uber.org/goleak"
)
func TestMain(m *testing.M) {
goleak.VerifyTestMain(m)
}
Packages to instrument (those with go func / WaitGroup / fan-out): the root
unpixel, internal/search, blind, mosaictext, internal/blinddecode,
internal/fontrank, and cmd/unpixel. (Re-derive the list with
grep -rln 'go func\|sync.WaitGroup\|errgroup' --include='*.go' . | grep -v _test.go.)
If a package already has a TestMain, fold the goleak verification in around the
existing m.Run() and propagate its exit code; do not add a second one.
Per-test, sequential checks can use defer goleak.VerifyNone(t) — but never with
t.Parallel.
Go 1.26 profile (deeper, no false positives)
For a hard-to-pin leak, capture the GC-backed profile (proves stuck goroutines):
import "runtime/pprof"
pprof.Lookup("goroutineleak").WriteTo(os.Stderr, 1) // Go 1.26+, experimental
Use it to confirm a goleak finding is genuinely blocked (and on what) before fixing.
2. Run (ALWAYS caged)
NEVER run go test bare on this machine — it OOM-freezes Fedora. Always:
mise run leak # the dedicated gate (caged, CGO-free)
scripts/gotest-caged.sh go test ./internal/search # a single package
goleak needs no special flags — it runs via TestMain, so a plain caged go test
detects leaks. A leak prints as found unexpected goroutines with each one's stack — the
bottom frame is the go func that leaked; the top frame is where it is blocked.
No
-racein the gate. The race detector requiresCGO_ENABLED=1, and this project is pure Go, no CGO (an absolute rule — seeCLAUDE.md). goleak detects leaks without-race. Use-raceonly as a manual, local-only deep check for data races (a different class of bug):CGO_ENABLED=1 scripts/gotest-caged.sh go test -race ./...— never wire it into a committed task or the CI gates.
3. Known leak patterns in this repo
- Unconsumed
Progress/ results channel.(*Engine).Runreturns(<-chan Progress, <-chan Result). High-frequency events are drop-on-full (select … default), butEventNewBest/EventDoneand the result send must not block forever. A producer that does a blocking send on a channel the caller stopped reading leaks. Fixes: make the terminal sendselectonctx.Done(); buffer the results channel by 1; or document+guarantee the producer always returns when ctx is cancelled. Tests must drain to completion or cancel ctx. - Worker fan-out without join. Each fan-out (search offsets, font sweep, blinddecode
Cartesian, mosaictext sweeps) must
wg.Wait()(or errgroupWait()) on every return path, including early error/ctxcancellation. A worker blocked on a full results channel after the collector returned is a leak — give the results channel enough buffer, or have workersselectonctx.Done(). - Context not honored. A goroutine looping on work must check
ctx.Done(); atime.After/tickermust be stopped. Store nocontext.Contextin a struct. - Test-only background goroutines. A goroutine the test starts (e.g. draining progress) must finish before the test returns, or goleak attributes it to the package.
4. Fixing
Fix the production goroutine's lifecycle, not the test. The correct shapes:
- Owner holds the goroutine and exposes
Close/Stop, or the goroutine is bounded by aWaitGroupthe spawning function waits on before returning. - Every channel a goroutine sends on is either buffered enough that the send can't block
after consumers stop, or the send is
select { case ch<-v: case <-ctx.Done(): }. - Cancellation (
ctx) unblocks every goroutine; the function that created thectx(or derived acancel) callscancelon all paths (defer cancel()).
Suppress only a proven framework goroutine, narrowly:
goleak.VerifyTestMain(m, goleak.IgnoreTopFunction("<pkg>.<func>")) // reason: …
Done when
mise run leak is clean (CGO-free, caged), the recovery panel is still 17/17, and every
real leak was fixed in production code (suppressions, if any, name a proven-external
goroutine and a reason).