Go 'fatal error: all goroutines are asleep - deadlock!' with 'goroutine 1 [chan receive]' or '[semacquire]': what causes it and how do I fix it?

Cause: The Go runtime found that every goroutine is blocked and none can ever be woken, so it aborts the program. Typical causes: sending on an unbuffered channel with no receiver (or receiving with no sender); ranging over a channel that nobody closes; a sync.WaitGroup whose Wait() is called but Done() is called fewer times than Add() (or Add is called inside the goroutine after Wait started); locking a sync.Mutex twice in the same goroutine; and using a nil channel, because the spec says send and receive on a nil channel block forever. Per the Go docs, with an unbuffered channel the sender blocks until a receiver has received the value, and receivers block until data arrives. Fix: 1. Read the dump. The goroutine list shows what each goroutine is waiting on, such as chan send, chan receive, semacquire (WaitGroup or Mutex), or select (no cases). The line numbers point at the blocked operation. 2. Make sure every send has a matching receive running in another goroutine. Start the consumer with go before the producer sends, or use a buffered channel sized for the data. 3. Have the sender close the channel when finished so for range loops end. Only the sender should close, and never close twice. 4. For WaitGroup, call wg.Add(n) before starting the goroutines and defer wg.Done() inside each one. On Go 1.25 and newer you can use wg.Go(f), which does the bookkeeping for you. 5. Don't hold a mutex while calling code that tries to take it again; release it first or split into locked and unlocked helper functions. 6. Initialise channels with make; a nil channel never becomes ready. Caveat: this message appears only when all goroutines are stuck. If some goroutine is still running (an HTTP server, a timer, a goroutine blocked in a system call), a partial deadlock is not reported and you just see a hang; send SIGQUIT (Ctrl+\) to dump all goroutine stacks, or inspect them with the pprof goroutine profile. Verify: The program exits normally, and go test -race ./... passes. A test with a timeout (go test -timeout 30s) no longer hangs. Sources: https://go.dev/doc/effective_go https://go.dev/ref/spec https://pkg.go.dev/sync