samber/cc-skills-golang / skills/golang-troubleshooting
golang-troubleshooting
VerifiedTroubleshoot Golang programs systematically - find and fix the root cause. Use when encountering bugs, crashes, deadlocks, races, or unexpected behavior in Go code. Covers debugging methodology, common Go pitfalls, test-driven debugging, pprof setup and capture, Delve, race detection, GODEBUG tracing, and production debugging. Start here for any 'something is wrong' situation. Not for interpreting profiles or benchmarking (→ See `samber/cc-skills-golang@golang-benchmark` skill), applying optimization patterns (→ See `samber/cc-skills-golang@golang-performance` skill), or designing new code (→ See `samber/cc-skills-golang@golang-safety` skill for defensive coding, `samber/cc-skills-golang@golang-concurrency` skill for concurrency design).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.0 KB |
| evals/evals.json | config | 45.0 KB |
| references/code-review-flags.md | markdown | 1.9 KB |
| references/common-go-bugs.md | markdown | 25.4 KB |
| references/compilation.md | markdown | 647 B |
| references/concurrency-debug.md | markdown | 3.0 KB |
| references/diagnostic-tools.md | markdown | 3.6 KB |
| references/methodology.md | markdown | 10.0 KB |
| references/performance-debug.md | markdown | 1.5 KB |
| references/pprof.md | markdown | 5.1 KB |
| references/production-debug.md | markdown | 3.7 KB |
| references/testing-debug.md | markdown | 3.2 KB |
references/concurrency-debug.md
View on GitHub# Concurrency Debugging
## Table of Contents
- [Goroutine Leaks](#goroutine-leaks)
- [Race Conditions](#race-conditions)
- [Deadlocks](#deadlocks)
## Goroutine Leaks
**Symptoms:** Memory slowly increasing, goroutine count growing, no obvious CPU spike.
**Diagnosis:**
Use pprof goroutine profile (see [pprof.md](./pprof.md)) with `?debug=2` for human-readable output, then look for goroutines stuck in `chan receive`.
The goroutine leak profile (experimental behind `GOEXPERIMENT=goroutineleakprofile` in Go 1.26) is generally available since Go 1.27 — no build flag needed, and it is served at `/debug/pprof/goroutineleak` like any other standard profile.
```bash
curl http://localhost:6060/debug/pprof/goroutineleak?debug=2
go tool pprof http://localhost:6060/debug/pprof/goroutineleak
```
Keep existing tools: `go.uber.org/goleak` in tests, `runtime.NumGoroutine()` for coarse monitoring, `/debug/pprof/goroutine?debug=2` for stack dumps, and `go test -race ./...` for race checks.
```go
// Programmatic monitoring — log goroutine count to detect leaks
go func() {
for {
log.Printf("goroutines: %d", runtime.NumGoroutine())
time.Sleep(3 * time.Second)
}
}()
// In tests, use goleak to detect goroutine leaks
// import "go.uber.org/goleak"
// func TestMain(m *testing.M) { goleak.VerifyTestMain(m) }
```
**Common causes:**
```go
// 1. Unclosed channel — goroutine blocks forever
// BAD
for {
job := <-jobs
process(job)
}
// GOOD
for {
select {
case job, ok := <-jobs:
if !ok { return }
process(job)
case <-ctx.Done():
return
}
}
// 2. Forgotten response body close — leaks HTTP connection
// Always defer resp.Body.Close() after HTTP calls.
// See production-debug.md for the correct pattern.
// 3. time.After in hot loop — allocates a new timer each iteration
// BAD
for {
select {
case <-time.After(time.Second):
do()
}
}
// GOOD — reuse a ticker for repeated intervals
ticker := time.NewTicker(time.Second)
defer ticker.Stop()
for {
select {
case <-ticker.C:
do()
case <-ctx.Done():
return
}
}
```
## Race Conditions
**Symptoms:** Intermittent failures, "sometimes works sometimes doesn't", different results on different machines.
**Diagnosis:** Race conditions MUST be tested with the `-race` flag:
```bash
go test -race ./...
go run -race main.go
# Race detector slows code ~10x but finds data races reliably
```
**Common patterns:**
- Shared map without mutex
- Shared variable without atomic
- Publishing reference before initialization
- go func() accessing outer variables without synchronization
## Deadlocks
**Symptoms:** Program hangs, goroutines stuck in "chan receive" or "mutex lock".
**Diagnosis:**
```bash
curl http://localhost:6060/debug/pprof/goroutine?debug=2
# Or programmatic
runtime.Stack(buf, true)
```
**Common patterns:**
1. **Circular wait** — A waits for B, B waits for A
2. **Forgotten channel send** — sender goroutine exited
3. **Wrong lock order** — always acquire locks in the same order
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |