panic: test timed out after 10m0s

TL;DR

go test kills any package that runs longer than its timeout (default 10m) and panics with a stack dump. The quick relief is -timeout 30m; the real fix is finding which test hung, using the goroutine stacks in the panic output or re-running with -v to see the last test that started.

Error

panic: test timed out after 10m0s
running tests:
    TestProcessLargeFile (600s)

Steps

1. Re-run just the stuck package with a longer timeout: go test -timeout 30m -run TestProcessLargeFile ./pkg/worker. Expected: the package completes, or you get a fresh stack dump to read.
2. If it still hangs, read the panic's goroutine stacks and find the one inside your test code. Expected: you see the function and line where it waits (channel receive, mutex, network read).
3. Fix the hang at its source: a test waiting on a channel nobody closes needs the missing close or a timeout branch. Expected: the test finishes on its own.
4. If the suite is legitimately slow, make the longer timeout permanent in CI, e.g. go test -timeout 20m ./.... Expected: CI stops killing healthy slow suites.
5. For a suite you own, split it: move the slow test to its own package or add t.Parallel where safe. Expected: wall time drops back under the default.

When to use

• The panic names a test and a duration like 10m0s.
• A suite that used to pass now times out (input grew, or CI got slower).
• The hang reproduces with -run on a single test.

When not to use

• Tests FAIL with assertion diffs (a logic bug, not a hang).
• The package does not build (compile error, different fix).
• panic: runtime error like nil pointer dereference (a crash, not a timeout).

Tool compatibility

• Go 1.16 and newer, go test with the -timeout flag.
• Works the same under testify suites and plain testing.

Variant phrasings

test timed out after 5m0s

Someone set -timeout 5m explicitly. Same diagnosis, just a shorter fuse.

panic: test timed out with no test listed

The hang is in TestMain or a package init, not a test function. Read the stacks for init or TestMain frames.

signal: killed

The OS killed the test binary, usually out of memory. That is resource exhaustion, not the go test watchdog.

Why it happens

The go test binary runs each package with a watchdog; when the deadline passes it panics and dumps every goroutine's stack. A deadlock on an unbuffered channel, a network call with no deadline, or a test that legitimately takes 12 minutes all trip it.

Edge cases

• -timeout 0 disables the watchdog entirely; fine for local debugging, never in CI.
• The stack dump lists testing.tRunner frames first; your code is further down the trace.
• Parallel subtests each hold the clock, so one slow subtest can doom the whole package.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_m5O4iYUNUAptpUZwAZVAng