golang-troubleshooting

Debug Go crashes, panics, deadlocks, and unexpected behavior through evidence-based root-cause analysis.

4|Updated May 17, 2026
One-click install
npx skills add https://github.com/hellopoisonx/aim --skill golang-troubleshooting-hellopoisonx
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: golang-troubleshooting
Source: https://github.com/hellopoisonx/aim/tree/main/skills/golang-troubleshooting
Command: npx skills add https://github.com/hellopoisonx/aim --skill golang-troubleshooting-hellopoisonx

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Golang troubleshooting helps you systematically debug Go crashes, deadlocks, panics, hangs, and unexpected behavior by starting from the real error signals and working backward to the root cause rather than applying guess-based symptom fixes.

Core Features & Use Cases

  • Decision-first debugging: Use a structured decision tree to pick the right diagnostic path based on what you are seeing (build failures, logic bugs, panics, hangs, CPU/memory spikes).
  • Golden-rule methodology: Read the error, reproduce before fixing, test one hypothesis at a time, and trace the bug to its origin.
  • Practical evidence tools: Guidance for test-driven reproduction, race detection, pprof workflows (including goroutine/heap profiles), Delve debugging, and GODEBUG tracing.
  • Common Go pitfall coverage: Focused explanations for frequent production bugs such as typed-nil interface gotchas, WaitGroup misuse, defer-in-loop leaks, concurrent map fatal errors, context misuse, and production-safe observability.
  • Reference-based escalation: Clear “start simple, escalate incrementally” approach, including when to use pprof, Delve, and production-oriented checklists.

Quick Start

Tell the skill: "I’m seeing a panic/deadlock/hang in my Go service—here is the full stack trace/logs and the smallest code path to reproduce it; guide me step-by-step to locate the root cause using tests, race detection, and pprof/Delve as needed."

Frequently Asked Questions about golang-troubleshooting

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

FAQPage Schema
How do I find the root cause of a Go panic or deadlock?

To find the root cause of a Go panic or deadlock, read the error, reproduce it before fixing, and test one hypothesis at a time. This structured approach prevents guess-based symptom fixes.

How do I use pprof and Delve to troubleshoot unexpected behavior in Golang?

You use pprof and Delve to troubleshoot unexpected behavior in Golang by following an incremental escalation path. Start with test-driven reproduction, then use pprof for goroutine/heap profiles and Delve for step debugging.

What is the best way to debug intermittent concurrent map fatal errors in Go?

The best way to debug intermittent concurrent map fatal errors in Go is to use race detection during test-driven reproduction. This identifies the specific concurrent access patterns causing the crashes.

When do I need GODEBUG tracing for troubleshooting Go program failures?

You need GODEBUG tracing for troubleshooting Go program failures when diagnosing environment-dependent issues that require production-safe diagnostics. It provides runtime instrumentation to trace complex bugs without heavy profilers.

Does this systematic debugging approach work for typed-nil interface and WaitGroup misuse bugs?

Yes, this systematic debugging approach works for typed-nil interface and WaitGroup misuse bugs. It includes focused explanations and a decision tree to classify these common Go pitfalls and trace them to their origin.