golang-troubleshooting

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

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

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 wastes time and creates new bugs. This Skill enforces a systematic, evidence-driven debugging methodology so you find the actual root cause instead of patching symptoms. ## Core Features & Use Cases - Systematic Debugging Methodology: A 10-step process with Golden Rules (reproduce before fixing, one hypothesis at a time, trace to root cause) plus a quick decision tree mapping symptoms to the right diagnostic path. - Common Go Bug Catalog: Documented pitfalls with reproduction patterns and fixes — interface nil gotcha, variable shadowing, defer-in-loop leaks, concurrent map access, JSON float64 surprises, and more. - Diagnostic Tooling Guidance: Practical references for pprof profiling (CPU, heap, goroutine, mutex, block), the race detector, GODEBUG tracing, Delve debugger, and production debugging with secure pprof setup. - Use Case: Your Go service intermittently crashes with 'concurrent map read and map write' despite recover() middleware. The Skill explains why this fatal error bypasses recover, and walks you through reproducing it with go test -race and fixing it with proper mutex synchronization. ## 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 using this troubleshooting skill.

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 or crashes intermittently?▼

Start by reproducing the failure with a failing test, then run go test -race ./... to detect data races and set GOTRACEBACK=all for full stack traces. Follow a one-hypothesis-at-a-time methodology rather than guessing at fixes.

How do I find goroutine leaks in a Go application?▼

Capture a goroutine profile with curl localhost:6060/debug/pprof/goroutine?debug=2 and look for goroutines stuck in chan receive. In tests, use go.uber.org/goleak, and monitor runtime.NumGoroutine() for growth trends.

Why does my Go error check pass even when the error is nil?▼

This is the interface nil gotcha: a typed nil pointer wrapped in an error interface is not a nil interface. Return nil explicitly instead of returning a typed nil variable like var err *MyError.

Can I expose pprof endpoints in production Go services?▼

Yes, but pprof endpoints must be protected with basic auth and ideally run on a separate port or localhost only. Toggle them via an environment variable like PPROF_ENABLED, since they leak goroutine stacks and memory contents.

Why doesn't recover() catch panics from my goroutines?▼

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

When should I use Delve versus pprof for Go debugging?▼

Use Delve for breakpoint-based debugging of specific code paths and inspecting variables during execution. Use pprof for profiling CPU, heap, goroutines, mutex contention, and blocking behavior in running services.