go-troubleshooting
Systematic troubleshooting and debugging for Golang programs. Covers panics, deadlocks, race conditions, and performance issues.
SKILL.mdskills/go/go-troubleshooting/SKILL.md
GitHubTroubleshooting Methodology
- Read the Error — Go error messages and stack traces are precise. Identify the file and line number.
- Reproduce — Create a minimal, deterministic test case that fails.
- Isolate — Strip away unrelated code until only the bug remains.
- Hypothesize — Form one explanation for the bug and test it.
- Measure — Use tools (
pprof,-race) to confirm your hypothesis. - Fix Root Cause — Avoid "band-aid" fixes. Ensure you understand why the fix works.
Decision Tree: What are you seeing?
| Symptom | Action |
|---|---|
| Build won't compile | go build ./... and check type/import errors. |
| Logic bug | Write a failing test; check error handling and nil pointers. |
| Random crashes / Panics | Check stack trace; run with GOTRACEBACK=all. |
| Race conditions | Run tests with go test -race ./.... |
| Program hangs | Capture goroutine profile: curl .../debug/pprof/goroutine?debug=2. |
| High CPU/Memory | Use pprof CPU or heap profiling. |
Common Go Bugs
- Nil Pointer Dereference: Accessing a field/method on a nil pointer.
- Interface Nil Gotcha: A typed nil pointer inside an interface is NOT nil.
- Concurrent Map Access: Writing to a map from multiple goroutines without a lock.
- Goroutine Leak: Spawning goroutines that never exit.
- Variable Shadowing: Accidental redeclaration of a variable in a nested scope (e.g.,
err := ...).
Debugging Tools
go test -race: Detects data races.delve(dlv): Full-featured debugger for setting breakpoints and inspecting state.pprof: Profiling CPU, memory, and blocking operations.GODEBUG: Environment variables for tracing GC (gctrace=1) or the scheduler (schedtrace=1000).
Anti-patterns in Debugging
- ❌ Guessing fixes — "Maybe adding a nil check here helps."
- ❌ treating symptoms — Fixing a crash without understanding the invalid state that caused it.
- ❌ Multiple changes at once — You won't know which one fixed the issue (or broke something else).
- ❌ Ignoring
-raceoutput — Races are undefined behavior; fix every single one. - ❌ Leaving
fmt.Println— Use a structured logger (slog) for persistent diagnostics.