golang-troubleshooting

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

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

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Go programs fail in subtle ways — typed-nil interfaces, shadowed error variables, goroutine leaks, and race conditions that pass tests but crash in production. This Skill enforces a systematic debugging methodology that finds the actual root cause instead of applying symptom-masking fixes. ## Core Features & Use Cases - Systematic Debugging Methodology: A 10-step process covering reproduction, hypothesis testing, root-cause tracing, and defense-in-depth, with a quick decision tree mapping symptoms to the right diagnostic path. - Common Go Pitfall Catalog: Documented patterns for nil pointer dereferences, interface nil gotchas, defer-in-loop leaks, concurrent map access, WaitGroup misuse, JSON float64 surprises, and more — each with reproductions and fixes. - Diagnostic Tooling Guidance: Practical references for pprof profiling (CPU, heap, goroutine, mutex, block), the race detector, GODEBUG tracing, Delve debugger, and production debugging with proper pprof authentication. - Use Case: A Go service intermittently crashes with 'concurrent map read and map write' despite recover middleware. The Skill explains why this fatal error bypasses recover, then guides you to protect the map with sync.RWMutex and confirm with go test -race. ## Quick Start Ask the agent to debug your Go issue, for example: my Go server hangs under load, 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 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, missing map keys, and uninitialized struct fields.

How do I find race conditions in Go code?▼

Run tests with the -race flag: go test -race ./... or go run -race main.go. The race detector slows execution roughly 10x but reliably finds data races such as shared maps without mutexes and unsynchronized variable access.

Why does my Go error check pass even when no error occurred?▼

This is the interface nil gotcha: returning a typed nil pointer as an error interface produces a non-nil interface. Fix it by returning nil explicitly instead of returning the typed nil variable.

How do I profile CPU and memory usage in a Go application?▼

Enable pprof endpoints and capture profiles with curl, for example /debug/pprof/profile?seconds=30 for CPU and /debug/pprof/heap for memory, then analyze with go tool pprof. In production, protect pprof with basic auth and gate it behind an environment variable.

Why does my Go program hang or leak goroutines over time?▼

Goroutine leaks usually come from unclosed channels, forgotten context cancellation, or missing response body closes. Capture a goroutine dump via /debug/pprof/goroutine?debug=2 and look for goroutines stuck in chan receive, and use goleak in tests.

When should I use Delve instead of print debugging in Go?▼

Start with fmt.Println or structured logging for simple reproducible bugs. Escalate to Delve (dlv debug, dlv test, dlv attach) when you need breakpoints, variable inspection, and goroutine switching that logging cannot provide.