Go deadlock — all goroutines are asleep

What causes this error

Go's runtime detects a deadlock when every goroutine is blocked: on a channel send with no receiver, on a channel receive with no sender, waiting to acquire a mutex that will never be released, or in a select with no cases that can proceed. Partial deadlocks (some goroutines still running) are not detected by the runtime and require external tooling like `pprof`.

How to fix it

1. 01

   step 1

   Read the goroutine dump in the panic output

   Go prints the stack trace of every goroutine when a deadlock is detected. Each blocked goroutine shows the exact file and line where it's waiting. Find the goroutines waiting on channels or mutexes.

   # Deadlock output includes all goroutine stacks:
   # goroutine 1 [chan receive]:
   #     main.main()
   #         /app/main.go:10 +0x...  ← blocked here
   # goroutine 6 [chan send]:
   #     main.worker()
   #         /app/worker.go:25 +0x...  ← blocked here
   
   # Enable full goroutine dump on any signal
   kill -SIGQUIT <pid>   # prints all goroutine stacks to stderr

   Copy
2. 02

   step 2

   Fix channel direction — ensure every send has a receiver

   Every unbuffered channel send must have a matching receive on the other side in a different goroutine — both sides must be ready simultaneously. If the sender is in main() and there's no goroutine reading, it deadlocks immediately.

   // BAD — send and receive both in main() sequentially
   ch := make(chan int)
   ch <- 1    // deadlock: main blocks here, never reaches receive
   val := <-ch
   
   // GOOD — send in goroutine, receive in main
   ch := make(chan int)
   go func() {
       ch <- 1  // goroutine sends
   }()
   val := <-ch  // main receives — works

   Copy
3. 03

   step 3

   Check for double-lock on sync.Mutex

   Calling `mu.Lock()` twice from the same goroutine causes a deadlock — Go's `sync.Mutex` is not reentrant. A function that locks, then calls another function that also locks the same mutex, will deadlock.

   var mu sync.Mutex
   
   func A() {
       mu.Lock()
       defer mu.Unlock()
       B()  // B also locks mu — DEADLOCK
   }
   
   func B() {
       mu.Lock()    // blocks forever — A already holds the lock
       defer mu.Unlock()
       // ...
   }
   
   // Fix: use sync.RWMutex, or restructure so B is called without the lock held,
   // or extract the shared logic into an unexported function that assumes the lock is held.

   Copy
4. 04

   step 4

   Use select with a default or context cancellation for non-blocking channel ops

   When you want to try sending/receiving on a channel without blocking indefinitely, use `select` with a `default` case or a `context.Done()` case.

   // Non-blocking receive
   select {
   case val := <-ch:
       fmt.Println("got:", val)
   default:
       fmt.Println("no value ready")
   }
   
   // With context cancellation (prevents goroutine leak)
   func worker(ctx context.Context, ch <-chan int) {
       for {
           select {
           case val := <-ch:
               process(val)
           case <-ctx.Done():
               return  // clean exit
           }
       }
   }

   Copy

How to verify the fix

• The program completes without printing 'all goroutines are asleep'.
• Run `go run -race ./...` — the race detector also catches some deadlock patterns.
• Use `pprof` mutex profile to confirm no goroutines are permanently blocked.