go-troubleshooting

Go Troubleshooting

Diagnosis before fixes. Reproduce, observe, localize, then change code. Never "fix" a symptom you haven't explained — the bug will move.

1. Pick the Procedure by Symptom

Symptom	Procedure
Crash with stack trace	§2 Read the panic
Program hangs / requests stall	§3 Dump goroutines, find the block
fatal error: all goroutines are asleep	§3 — Go detected total deadlock
Memory grows until OOM	§4 Heap profile diff
Goroutine count grows	§5 Goroutine profile diff
Intermittent corrupt data / weird values	§6 Race detector
Need to inspect state interactively	§7 Delve

2. Reading a Panic

panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x0 pc=0x6bb0e4]

goroutine 43 [running]:
myapp/internal/service.(*UserService).Notify(0x0, {0xc000123456?, ...})
        /app/internal/service/user.go:87 +0x24
myapp/internal/handler.(*Handler).Create(0xc0001a2000, ...)
        /app/internal/handler/user.go:41 +0x1c5

Read it mechanically:

1. First line: what kind of panic. nil pointer dereference + addr=0x0 means a nil receiver, nil field, or nil map/pointer argument.
2. Top frame in YOUR code: user.go:87 — go there.
3. Receiver value in the frame: (*UserService).Notify(0x0, ...) — the 0x0 first argument IS the receiver: the service itself was nil. Trace where it was constructed (or wasn't).
4. goroutine 43 — if it's not goroutine 1, find who spawned it and whether a recover boundary should exist there.

3. Hangs and Deadlocks

Get a goroutine dump from the hanging process:

kill -QUIT <pid>      # dumps all goroutine stacks to stderr, then exits
# or, if net/http/pprof is mounted (see §4):
curl 'localhost:6060/debug/pprof/goroutine?debug=2'

Then classify the stacks:

• [semacquire] on sync.(*Mutex).Lock — find which goroutine HOLDS the mutex: look for another stack inside the critical section. Two goroutines each holding one of two locks = lock-order inversion.
• [chan send] / [chan receive] — the other side is gone. Find who should be receiving/sending and why it exited (or was never started).
• [select] with a ctx.Done() case missing — blocked call that ignores cancellation.
• Hundreds of identical stacks — that's a leak (§5), not a deadlock.