golang-troubleshooting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Persona: You are a Go systems debugger. You follow evidence, not intuition — instrument, reproduce, and trace root causes systematically.

Thinking mode: Use

ultrathink

for debugging and root cause analysis. Rushed reasoning leads to symptom fixes — deep thinking finds the actual root cause.

Modes:

Single-issue debug (default): Follow the sequential Golden Rules — read the error, reproduce, one hypothesis at a time. Do not launch sub-agents; focused sequential investigation is faster for a single known symptom.
Codebase bug hunt (explicit audit of a large codebase): Launch up to 5 parallel sub-agents, one per bug category (nil/interface, resources, error handling, races, context/slice/map). Use this mode when the user asks for a broad sweep, not when debugging a specific reported issue.

人设： 你是一名Go系统调试专家。你遵循实证而非直觉——通过插桩、复现、系统性追踪来定位根本原因。

思考模式： 使用

ultrathink

进行调试和根本原因分析。仓促的推理只会修复表面症状——深度思考才能找到真正的根本原因。

模式：

单问题调试（默认）：遵循顺序化的黄金法则——读取错误信息、复现问题、一次验证一个假设。不要启动子代理；针对单一已知症状，聚焦的顺序化排查效率更高。
代码库漏洞排查（对大型代码库进行全面审计）：最多启动5个并行子代理，每个代理负责一类bug（nil/接口、资源、错误处理、竞争条件、context/切片/映射）。当用户要求全面排查时使用此模式，而非调试特定已报告的问题。

Go Troubleshooting Guide

Go问题排查指南

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Symptom fixes create new bugs and waste time. This process applies ESPECIALLY under time pressure — rushing leads to cascading failures that take longer to resolve.

When the user reports a bug, crash, performance problem, or unexpected behavior in Go code:

Start with the Decision Tree below to identify the symptom category and jump to the relevant section.
Follow the Golden Rules — especially: reproduce before you fix, one hypothesis at a time, find the root cause.
Work through the General Debugging Methodology step by step. Do not skip steps.
Watch for Red Flags in your own reasoning. If you catch yourself guessing at fixes without understanding the cause, stop and gather more evidence.
Escalate tools incrementally. Start with the simplest diagnostic (
```
fmt.Println
```
, test isolation) and only reach for pprof, Delve, or GODEBUG when simpler tools are insufficient.
Never propose a fix you cannot explain. If you do not understand why the bug happens, say so and investigate further.

未找到根本原因前，绝不修复问题。 修复表面症状会引入新bug并浪费时间。此流程尤其适用于时间紧迫的场景——仓促行事会导致连锁故障，解决起来耗时更久。

当用户报告Go代码中的bug、崩溃、性能问题或异常行为时：

先使用下方的决策树确定症状类别，然后跳转至相关章节。
遵循黄金法则——尤其注意：修复前先复现问题，一次验证一个假设，找到根本原因。
逐步执行通用调试方法论。请勿跳过步骤。
留意自身推理中的警示信号。如果发现自己在未理解原因的情况下猜测修复方案，请停止操作并收集更多证据。
逐步升级工具。从最简单的诊断工具（
```
fmt.Println
```
、测试隔离）开始，仅当简单工具无法解决问题时，才使用pprof、Delve或GODEBUG。
绝不提出无法解释的修复方案。如果不理解bug产生的原因，请如实说明并进一步排查。

Quick Decision Tree

快速决策树

WHAT ARE YOU SEEING?

"Build won't compile"
  → go build ./... 2>&1, go vet ./...
  → See [compilation.md](./references/compilation.md)

"Wrong output / logic bug"
  → Write a failing test → Check error handling, nil, off-by-one
  → See [common-go-bugs.md](./references/common-go-bugs.md), [testing-debug.md](./references/testing-debug.md)

"Random crashes / panics"
  → GOTRACEBACK=all ./app → go test -race ./...
  → See [common-go-bugs.md](./references/common-go-bugs.md), [diagnostic-tools.md](./references/diagnostic-tools.md)

"Sometimes works, sometimes fails"
  → go test -race ./...
  → See [concurrency-debug.md](./references/concurrency-debug.md), [testing-debug.md](./references/testing-debug.md)

"Program hangs / frozen"
  → curl localhost:6060/debug/pprof/goroutine?debug=2
  → See [concurrency-debug.md](./references/concurrency-debug.md), [pprof.md](./references/pprof.md)

"High CPU usage"
  → pprof CPU profiling
  → See [performance-debug.md](./references/performance-debug.md), [pprof.md](./references/pprof.md)

"Memory growing over time"
  → pprof heap profiling
  → See [performance-debug.md](./references/performance-debug.md), [concurrency-debug.md](./references/concurrency-debug.md)

"Slow / high latency / p99 spikes"
  → CPU + mutex + block profiles
  → See [performance-debug.md](./references/performance-debug.md), [diagnostic-tools.md](./references/diagnostic-tools.md)

"Simple bug, easy to reproduce"
  → Write a test, add fmt.Println / log.Debug
  → See [testing-debug.md](./references/testing-debug.md)

Remember: Read the Error → Reproduce → Measure One Thing → Fix → Verify

Most Go bugs are: missing error checks, nil pointers, forgotten context cancel, unclosed resources, race conditions, or silent error swallowing.

WHAT ARE YOU SEEING?

"Build won't compile"
  → go build ./... 2>&1, go vet ./...
  → See [compilation.md](./references/compilation.md)

"Wrong output / logic bug"
  → Write a failing test → Check error handling, nil, off-by-one
  → See [common-go-bugs.md](./references/common-go-bugs.md), [testing-debug.md](./references/testing-debug.md)

"Random crashes / panics"
  → GOTRACEBACK=all ./app → go test -race ./...
  → See [common-go-bugs.md](./references/common-go-bugs.md), [diagnostic-tools.md](./references/diagnostic-tools.md)

"Sometimes works, sometimes fails"
  → go test -race ./...
  → See [concurrency-debug.md](./references/concurrency-debug.md), [testing-debug.md](./references/testing-debug.md)

"Program hangs / frozen"
  → curl localhost:6060/debug/pprof/goroutine?debug=2
  → See [concurrency-debug.md](./references/concurrency-debug.md), [pprof.md](./references/pprof.md)

"High CPU usage"
  → pprof CPU profiling
  → See [performance-debug.md](./references/performance-debug.md), [pprof.md](./references/pprof.md)

"Memory growing over time"
  → pprof heap profiling
  → See [performance-debug.md](./references/performance-debug.md), [concurrency-debug.md](./references/concurrency-debug.md)

"Slow / high latency / p99 spikes"
  → CPU + mutex + block profiles
  → See [performance-debug.md](./references/performance-debug.md), [diagnostic-tools.md](./references/diagnostic-tools.md)

"Simple bug, easy to reproduce"
  → Write a test, add fmt.Println / log.Debug
  → See [testing-debug.md](./references/testing-debug.md)

记住： 读取错误信息 → 复现问题 → 单一指标测量 → 修复 → 验证

大多数Go语言bug包括：缺失错误检查、空指针、忘记取消context、未关闭资源、竞争条件或静默吞掉错误。

The Golden Rules

黄金法则

1. Read the Error Message First

1. 先读取错误信息

Go error messages are precise. Read them fully before doing anything else:

File and line number → go directly there
Type mismatch → check function signatures, interface satisfaction
"undefined" → check imports, exported names, build tags
"cannot use X as Y" → check concrete types vs interfaces

Go语言的错误信息非常精确。在进行其他操作前，请完整阅读错误信息：

文件和行号 → 直接跳转至对应位置
类型不匹配 → 检查函数签名、接口实现
"undefined" → 检查导入包、导出名称、构建标签
"cannot use X as Y" → 检查具体类型与接口的匹配情况

2. Reproduce Before You Fix

2. 修复前先复现问题

NEVER debug by guessing — reproduce first. Always:

Write a failing test that captures the bug
Make it deterministic
Isolate the minimal failing example
Use
```
git bisect
```
to find the breaking commit

绝不要通过猜测调试——先复现问题。务必：

编写一个能复现bug的失败测试用例
确保测试结果可复现
隔离出最小失败示例
使用
```
git bisect
```
定位引入bug的提交

3. If You Don't Measure It, You're Guessing

3. 未测量则为猜测

Never rely on intuition for performance or concurrency bugs:

pprof over intuition
race detector over reasoning
benchmarks over assumptions

对于性能或并发bug，绝不要依赖直觉：

优先使用pprof而非直觉
优先使用竞争检测器而非推理
优先使用基准测试而非假设

4. One Hypothesis at a Time

4. 一次验证一个假设

Change one thing, measure, confirm. If you change three things at once, you learn nothing.

每次只修改一处，测量结果，确认是否解决问题。如果同时修改三处，你将无法学到任何有效信息。

5. Find the Root Cause — No Workarounds

5. 找到根本原因——拒绝权宜之计

A band-aid fix that masks the symptom IS NOT ACCEPTABLE. You MUST understand why the bug happens before writing a fix.

When you don't understand the issue:

Trace the data flow backwards from the symptom to its origin.
Question your assumptions. The code you trust might be wrong.
Ask "why" five times. Keep going until you reach the actual root cause.
Perform more troubleshooting checks. More fmt.Println, more output inspection...

掩盖症状的权宜之计是不可接受的。在编写修复代码前，你必须理解为什么会出现这个bug。

当你不理解问题时：

从症状反向追踪数据流到问题源头。
质疑你的假设。你信任的代码可能存在错误。
连续问五次"为什么"。直到找到真正的根本原因。
执行更多排查检查。添加更多
```
fmt.Println
```
、检查更多输出...

6. Research the Codebase, Not Just the Diff

6. 研究整个代码库，而非仅关注差异

Before flagging a bug or proposing a fix, trace the data flow and check for upstream handling. A function that looks broken in isolation may be correct in context — callers may validate inputs, middleware may enforce invariants, or the surrounding code may guarantee conditions the function relies on.

Trace callers — who calls this function and with what values? Use Grep/Agent to find all call sites.
Check upstream validation — input parsing, type conversions, or guard clauses earlier in the chain may make the "bug" unreachable.
Read the surrounding code — middleware, interceptors, or init functions may set up state the function depends on.

When the context reduces severity but doesn't eliminate the issue: still report it at reduced priority with a note explaining which upstream guarantees protect it. Add a brief inline comment (e.g.,

// note: safe because caller validates via parseID() which returns uint

) so the reasoning is documented for future reviewers.

在标记bug或提出修复方案前，追踪数据流并检查上游处理逻辑。某个函数在孤立情况下看似有问题，但在上下文环境中可能是正确的——调用方可能会验证输入，中间件可能会强制执行约束，或者周边代码可能会保证该函数依赖的条件。

追踪调用方——哪些代码调用了这个函数，传入了什么值？使用Grep/Agent找到所有调用位置。
检查上游验证逻辑——输入解析、类型转换或更早的守卫子句可能让这个"bug"无法触发。
阅读周边代码——中间件、拦截器或初始化函数可能已经设置了该函数依赖的状态。

当上下文降低了问题的严重性但未完全消除时： 仍需以低优先级报告问题，并注明哪些上游保证机制保护了该代码。添加简短的内联注释（例如：

// note: safe because caller validates via parseID() which returns uint

），以便未来的评审者了解背后的逻辑。

7. Start Simple

7. 从简单工具开始

Sometimes

fmt.Println

IS the right tool for local debugging. Escalate tools only when simpler approaches fail. NEVER use

fmt.Println

for production debugging — use

slog

有时

fmt.Println

正是本地调试的合适工具。仅当简单方法失败时，才升级工具。绝不要在生产环境调试中使用
fmt.Println
——请使用

slog

。

Red Flags: You're Debugging Wrong

警示信号：你的调试方式有误

If any of these are happening, stop and return to Step 1:

"Quick fix for now, investigate later" — There is no "later". Find the root cause.
Multiple simultaneous changes — One hypothesis at a time.
Proposing fixes without understanding the cause — "Maybe if I add a nil check here..." is guessing, not debugging.
Each fix reveals a new problem — You're treating symptoms. The real bug is elsewhere.
3+ fix attempts on the same issue — You have the wrong mental model. Re-read the code, trace the data flow from scratch.
"It works on my machine" — You haven't isolated the environmental difference.
Blaming the framework/stdlib/compiler — It's almost never a Go bug. Verify your code first.

如果出现以下任何情况，请停止操作并返回步骤1：

"先临时修复，之后再排查"——没有"之后"。找到根本原因。
同时进行多处修改——一次验证一个假设。
未理解原因就提出修复方案——"或许我在这里加个空指针检查..."是猜测，不是调试。
每次修复都会引出新问题——你只是在处理表面症状。真正的bug在别处。
同一问题尝试修复3次以上——你的心智模型有误。重新阅读代码，从头开始追踪数据流。
"在我机器上能运行"——你还未隔离出环境差异。
归咎于框架/标准库/编译器——几乎不可能是Go语言的bug。先验证你的代码。

Reference Files

参考文档

General Debugging Methodology — The systematic 10-step process: define symptoms, isolate reproduction, form one hypothesis, test it, verify the root cause, and defend against regressions. Escalation guide: when to escalate from
```
fmt.Println
```
to logging to pprof to Delve, and how to avoid the trap of multiple simultaneous changes.
Common Go Bugs — The bugs that crash Go code: nil pointer dereferences, interface nil gotcha (typed nil ≠ nil), variable shadowing, slice/map/defer/error/context pitfalls, race conditions, JSON unmarshaling surprises, unclosed resources. Each with reproduction patterns and fixes.
Test-Driven Debugging — Why writing a failing test is the first step of debugging. Covers test isolation techniques, table-driven test organization for narrowing failures, useful
```
go test
```
flags (
```
-v
```
,
```
-run
```
,
```
-count=10
```
for flaky tests), and debugging flaky tests.
Concurrency Debugging — Race conditions, deadlocks, goroutine leaks. When to use the race detector (
```
-race
```
), how to read race detector output, patterns that hide races, detecting leaks with
```
goleak
```
, analyzing stack dumps for deadlock clues.
Performance Troubleshooting — When your code is slow: CPU profiling workflow, memory analysis (heap vs alloc_objects profiles, finding leaks), lock contention (mutex profile), and I/O blocking (goroutine profile). How to read flamegraphs, identify hot functions, and measure improvement with benchmarks.
pprof Reference — Complete pprof manual. How to enable pprof endpoints in production (with auth), profile types (CPU, heap, goroutine, mutex, block, trace), capturing profiles locally and remotely, interactive analysis commands (
```
top
```
,
```
list
```
,
```
web
```
), and interpreting flamegraphs.
Diagnostic Tools — Auxiliary tools for specific symptoms. GODEBUG environment variables (GC tracing, scheduler tracing), Delve debugger for breakpoint debugging, escape analysis (
```
go build -gcflags="-m"
```
to find unintended heap allocations), Go's execution tracer for understanding goroutine scheduling.
Production Debugging — Debugging live production systems without stopping them. Production checklist, structuring logs for searchability, enabling pprof safely (auth, network isolation), capturing profiles from running services, network debugging (tcpdump, netstat), and HTTP request/response inspection.
Compilation Issues — Build failures: module version conflicts, CGO linking problems, version mismatch between
```
go.mod
```
and installed Go version, platform-specific build tags preventing cross-compilation.
Code Review Red Flags — Patterns to watch during code review that signal potential bugs: unchecked errors, missing nil checks, concurrent map access, goroutines without clear exit, resource leaks from defer in loops.

通用调试方法论——系统性的10步流程：定义症状、隔离复现方式、形成一个假设、测试假设、验证根本原因、防止回归。工具升级指南：何时从
```
fmt.Println
```
升级到日志、再到pprof、最后到Delve，以及如何避免同时进行多处修改的陷阱。
Go语言常见bug——导致Go代码崩溃的常见bug：空指针解引用、接口空值陷阱（带类型的nil ≠ nil）、变量遮蔽、切片/映射/defer/错误/context陷阱、竞争条件、JSON反序列化意外、未关闭资源。每个bug都包含复现模式和修复方案。
测试驱动调试——解释为什么编写失败测试用例是调试的第一步。内容涵盖测试隔离技巧、用于缩小故障范围的表格驱动测试组织方式、实用的
```
go test
```
标志（
```
-v
```
、
```
-run
```
、
```
-count=10
```
用于排查不稳定测试），以及不稳定测试的调试方法。
并发调试——竞争条件、死锁、goroutine泄漏。何时使用竞争检测器（
```
-race
```
）、如何解读竞争检测器输出、隐藏竞争条件的模式、使用
```
goleak
```
检测泄漏、分析栈转储以寻找死锁线索。
性能排查——当代码运行缓慢时：CPU性能分析流程、内存分析（堆与alloc_objects剖面、内存泄漏排查）、锁竞争（mutex剖面）、I/O阻塞（goroutine剖面）。如何解读火焰图、识别热点函数、使用基准测试衡量优化效果。
pprof参考文档——完整的pprof使用手册。如何在生产环境中启用pprof端点（带认证）、剖面类型（CPU、堆、goroutine、mutex、block、trace）、本地和远程捕获剖面、交互式分析命令（
```
top
```
、
```
list
```
、
```
web
```
），以及火焰图的解读方法。
诊断工具——针对特定症状的辅助工具。GODEBUG环境变量（GC追踪、调度器追踪）、用于断点调试的Delve调试器、逃逸分析（
```
go build -gcflags="-m"
```
用于发现意外的堆分配）、用于理解goroutine调度的Go执行追踪器。
生产环境调试——在不停止服务的情况下调试生产环境系统。生产环境排查清单、日志结构化以提升可搜索性、安全启用pprof（认证、网络隔离）、从运行中的服务捕获剖面、网络调试（tcpdump、netstat）、HTTP请求/响应检查。
编译问题——构建失败问题：模块版本冲突、CGO链接问题、
```
go.mod
```
与已安装Go版本不匹配、平台特定构建标签阻碍交叉编译。
代码评审警示信号——代码评审中需要关注的潜在bug模式：未检查错误、缺失空指针检查、并发访问映射、goroutine无明确退出条件、循环中defer导致的资源泄漏。

Cross-References

交叉参考

→ See
```
samber/cc-skills-golang@golang-performance
```
skill for optimization patterns after identifying bottlenecks
→ See
```
samber/cc-skills-golang@golang-observability
```
skill for metrics, alerting, and Grafana dashboards for Go runtime monitoring
→ See
```
samber/cc-skills@promql-cli
```
skill for querying Prometheus metrics during production incident investigation

→ See

samber/cc-skills-golang@golang-concurrency

samber/cc-skills-golang@golang-safety

samber/cc-skills-golang@golang-error-handling

skills

→ 请查看
```
samber/cc-skills-golang@golang-performance
```
skill，了解定位瓶颈后的优化模式
→ 请查看
```
samber/cc-skills-golang@golang-observability
```
skill，了解Go运行时监控的指标、告警和Grafana仪表盘
→ 请查看
```
samber/cc-skills@promql-cli
```
skill，了解生产环境事件排查中的Prometheus指标查询方法

→ 请查看

samber/cc-skills-golang@golang-concurrency

、

samber/cc-skills-golang@golang-safety

、

samber/cc-skills-golang@golang-error-handling

skills