fatal error: all goroutines are asleep - deadlock!

The exact error string

fatal error: all goroutines are asleep - deadlock!

goroutine 1 [chan send]:
main.main()
        /app/main.go:7 +0x37     <-- blocked sending on a channel

How to diagnose it

The fatal dump lists every goroutine and what it's blocked on in brackets: [chan send], [chan receive], [semacquire] (a mutex/WaitGroup). Read each one and ask "who is supposed to unblock this?" — the deadlock is the line where the answer is "nobody." Because Go only fires this when all goroutines are asleep, the dump is complete: the cause is in there.

Cause 1: unbuffered channel, no receiver

ch := make(chan int)
ch <- 1                 // ❌ blocks: no goroutine is receiving
fmt.Println(<-ch)

// ✅ receive in another goroutine
ch := make(chan int)
go func() { ch <- 1 }()
fmt.Println(<-ch)

// ✅ or buffer it if a single value is fine
ch := make(chan int, 1)
ch <- 1
fmt.Println(<-ch)

Cause 2: WaitGroup Done() never called

var wg sync.WaitGroup
wg.Add(2)
go func() { work(); wg.Done() }()  // only one Done() ...
wg.Wait()              // ❌ counter never reaches 0 -> deadlock

// ✅ defer Done() at the top, and Add the right count
wg.Add(2)
for i := 0; i < 2; i++ {
    go func() { defer wg.Done(); work() }()
}
wg.Wait()

Cause 3: range over a channel that's never closed

ch := make(chan int)
go func() {
    for i := 0; i < 3; i++ { ch <- i }
    // ❌ forgot to close(ch) — the range below blocks forever
}()
for v := range ch { fmt.Println(v) }

// ✅ close from the sender when done
go func() {
    defer close(ch)
    for i := 0; i < 3; i++ { ch <- i }
}()

Cause 4: a mutex locked twice (self-deadlock)

sync.Mutex is not reentrant: locking it again on the same goroutine before unlocking blocks forever. The stack shows [semacquire] rather than a channel op.

var mu sync.Mutex
mu.Lock()
mu.Lock()              // ❌ deadlock: already held by this goroutine

// ✅ lock once, and pair every Lock with an Unlock
mu.Lock()
defer mu.Unlock()
// ... critical section ...

// ❌ a common variant: a "locked" method calling another "locked" method
func (c *Cache) Get(k string) int { c.mu.Lock(); defer c.mu.Unlock(); return c.getLocked(k) }
func (c *Cache) getLocked(k string) int { c.mu.Lock(); ... }  // re-locks -> deadlock
// ✅ split into a public locking method and an internal non-locking helper

How Go detects deadlocks

The Go scheduler tracks how many goroutines exist and how many are runnable. Every time a goroutine blocks (on a channel, a sync.Mutex/RWMutex, a Cond, or a WaitGroup), that count drops. When the number of runnable goroutines reaches zero — nothing can make progress and nothing can wake anything — the runtime concludes the program is stuck and aborts with fatal error: all goroutines are asleep - deadlock!. It's a global check, not a per-goroutine one, which is exactly why it only fires when every goroutine is asleep (see below).

When the runtime won't catch it

Go reports this only when every goroutine is blocked. If one is still alive — an HTTP server, a time.Ticker, a background worker — a partial deadlock among the rest just hangs silently instead. For those, run with the race detector (go run -race), use go vet, or send SIGQUIT (Ctrl-\) to dump all goroutine stacks and see who's stuck.

A real-world example: the WaitGroup that never completes

A classic beginner scenario ties several of these together. You fan out work to goroutines, wait on a WaitGroup, but the counter never reaches zero:

func main() {
    var wg sync.WaitGroup
    results := make(chan int)      // unbuffered

    for i := 0; i < 3; i++ {
        wg.Add(1)
        go func(n int) {
            defer wg.Done()
            results <- n * n        // blocks: nobody is receiving yet
        }(i)
    }

    wg.Wait()                      // ❌ waits for workers that are all
                                   //    blocked sending on `results`
    for r := range results { fmt.Println(r) }
}

The chain is: the workers block sending on the unbuffered results channel → so Done() never runs → so wg.Wait() in main blocks forever → every goroutine is now asleep → deadlock. The fix is to drain the channel concurrently and close it after the group finishes:

go func() { wg.Wait(); close(results) }()  // ✅ waiter runs in the background
for r := range results {                    //    main drains as workers send
    fmt.Println(r)
}

Common causes at a glance

Debugging checklist

• ✓ Read each goroutine's [chan send/receive/semacquire] tag — what is it waiting for?
• ✓ Unbuffered send? Ensure a receiver runs concurrently (or buffer)
• ✓ WaitGroup? defer wg.Done() and make Add match the goroutines
• ✓ sync.Mutex? Lock once (it isn't reentrant) and pair with defer mu.Unlock()
• ✓ range ch? close(ch) from the sender when done
• ✓ Hangs but no fatal error? One goroutine is alive — use -race / SIGQUIT