golang-troubleshooting

Diagnose and fix root causes of bugs, crashes, and deadlocks in Go programs.

1|Updated Jun 2, 2026
One-click install
npx skills add https://github.com/VerifiedOrganic/onboard --skill golang-troubleshooting-verifiedorganic
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: golang-troubleshooting
Source: https://github.com/VerifiedOrganic/onboard/tree/main/.agents/skills/golang-troubleshooting
Command: npx skills add https://github.com/VerifiedOrganic/onboard --skill golang-troubleshooting-verifiedorganic

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires dlv, and includes references (resource) components.

What problem does it solve? Go programs fail in subtle ways — nil pointer panics, race conditions, goroutine leaks, silent error swallowing — and guessing at fixes creates new bugs. This Skill enforces a systematic debugging methodology that finds the actual root cause before any fix is applied. ## Core Features & Use Cases - Symptom Decision Tree: Routes any reported issue (crashes, hangs, high CPU, memory growth, flaky tests) to the right diagnostic workflow and reference guide. - Golden Rules Enforcement: Requires reproduction with a failing test, one hypothesis at a time, and root-cause tracing before proposing fixes. - Tooling Coverage: Step-by-step guidance for pprof profiling, Delve debugger, race detector, GODEBUG tracing, and production debugging with secured pprof endpoints. - Use Case: A Go service intermittently crashes with 'concurrent map read and map write' despite recover() middleware. The Skill explains this is a fatal unrecoverable error, then guides you to find the race with go test -race and protect the map with sync.RWMutex. ## Quick Start Ask the agent to debug your Go issue, for example: my Go server hangs after a few hours, help me find the root cause.

Frequently Asked Questions about golang-troubleshooting

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a Go program that panics with nil pointer dereference?▼

Read the stack trace to find the exact line, then trace backward to where the nil value originated rather than adding a nil check at the crash site. Common causes are unchecked error returns, map lookups returning zero values, and uninitialized struct fields.

How do I find race conditions in Go code?▼

Run tests or the binary with the race detector: go test -race ./... or go run -race main.go. It slows execution roughly 10x but reliably reports data races with full stack traces of the conflicting accesses.

Why does my Go program use 100% CPU when idle?▼

A common cause is a select statement with a default case inside a for loop, which busy-spins when no channel is ready. Another cause is reading from a closed channel in select, which fires continuously; fix it with the comma-ok idiom and nil-ing the channel.

Can recover() catch panics from child goroutines in Go?▼

No. recover() only catches panics in the same goroutine where it is deferred. A panic in a child goroutine crashes the entire process, so each goroutine needs its own deferred recover.

Is it safe to expose pprof endpoints in production Go services?▼

Not without protection. pprof leaks goroutine stacks and memory contents and can be abused for DoS. Gate it behind an environment variable, require basic auth, and bind it to a separate port or localhost.

When should I use Delve instead of fmt.Println for Go debugging?▼

Start with fmt.Println or structured logging for simple, reproducible bugs. Escalate to Delve breakpoints when you need to inspect live state, step through execution, or attach to a running process that simpler instrumentation cannot explain.