Go Troubleshooting
Find the causal chain before recommending a fix. Keep diagnostic evidence, root-cause claims, and any subsequent code change distinct.
Start with the Symptom
Record expected behavior, actual behavior, exact error or stack, frequency, environment, inputs, first known bad version, and recent relevant changes. Preserve raw evidence before reducing it to a theory.
Route by symptom:
| Symptom |
First evidence |
Reference |
| Compile, link, module, CGO, or build-tag failure |
Exact build command and complete diagnostics |
references/compilation.md |
| Wrong output or panic |
Minimal reproduction, full stack, data-flow trace |
references/common-go-bugs.md |
| Intermittent failure, race, hang, or goroutine growth |
Repetition, race detector, goroutine dump or trace |
references/concurrency-debug.md |
| Slow, high CPU, memory growth, or contention |
Profile or trace from representative load |
references/performance-debug.md |
| Failing or flaky test |
Isolated command, cache/order/parallel controls |
references/testing-debug.md |
| Live incident |
Existing telemetry and authorized low-risk capture |
references/production-debug.md |
Use references/methodology.md for the shared investigation loop.
Investigation Rules
- Reproduce before editing when practical. If reproduction is unsafe or impossible, state that and rely on the strongest available production evidence.
- Test one hypothesis at a time and keep observations separate from inferences.
- Trace the failing value, state, or resource backward to where its invariant first became false.
- Read callers, middleware, initialization, build constraints, configuration, and external dependencies before declaring a local line defective.
- Compare with a nearby working path when it shares the same contract.
- Escalate diagnostics from focused logs/tests to race, trace, profiles, or a debugger according to the symptom. Read references/diagnostic-tools.md when basic evidence is insufficient.
- Do not install tools, expose endpoints, attach to processes, restart services, capture customer data, or mutate external systems without the authorization required for that action.
Root-Cause Standard
A root-cause explanation should connect:
- the triggering conditions;
- the first violated invariant;
- the propagation path;
- why the observed symptom follows;
- evidence that distinguishes this explanation from alternatives.
An added nil check, retry, delay, or larger buffer is not a root cause by itself. It may still be the correct fix if the API contract says the boundary must tolerate that condition; explain why.
Fix and Verify
Prefer a regression test that fails for the observed condition and passes after the fix, but do not invent an unreliable test merely to satisfy a ritual.
After a fix:
- rerun the exact reproduction;
- run affected tests and static analysis;
- add race, integration, cross-platform, or profile comparison checks as warranted;
- remove temporary instrumentation or clearly identify intentional observability changes;
- review whether the same invalid state can enter through another path.
Deliverable
Report reproduction status, evidence collected, confirmed root cause or ranked remaining hypotheses, the scope of any fix, verification results, and uncertainty. Distinguish unavailable evidence from evidence that disproves a hypothesis.
1---2name: golang-troubleshooting3description: Diagnose Go build failures, panics, wrong results, hangs, races, leaks, flaky tests, and production runtime symptoms using reproducible evidence and appropriate Go diagnostics. Use when a Go problem's cause is unknown or competing hypotheses need to be separated.4license: MIT5---67# Go Troubleshooting89Find the causal chain before recommending a fix. Keep diagnostic evidence, root-cause claims, and any subsequent code change distinct.1011## Start with the Symptom1213Record expected behavior, actual behavior, exact error or stack, frequency, environment, inputs, first known bad version, and recent relevant changes. Preserve raw evidence before reducing it to a theory.1415Route by symptom:1617| Symptom | First evidence | Reference |18| --- | --- | --- |19| Compile, link, module, CGO, or build-tag failure | Exact build command and complete diagnostics | [references/compilation.md](references/compilation.md) |20| Wrong output or panic | Minimal reproduction, full stack, data-flow trace | [references/common-go-bugs.md](references/common-go-bugs.md) |21| Intermittent failure, race, hang, or goroutine growth | Repetition, race detector, goroutine dump or trace | [references/concurrency-debug.md](references/concurrency-debug.md) |22| Slow, high CPU, memory growth, or contention | Profile or trace from representative load | [references/performance-debug.md](references/performance-debug.md) |23| Failing or flaky test | Isolated command, cache/order/parallel controls | [references/testing-debug.md](references/testing-debug.md) |24| Live incident | Existing telemetry and authorized low-risk capture | [references/production-debug.md](references/production-debug.md) |2526Use [references/methodology.md](references/methodology.md) for the shared investigation loop.2728## Investigation Rules2930- Reproduce before editing when practical. If reproduction is unsafe or impossible, state that and rely on the strongest available production evidence.31- Test one hypothesis at a time and keep observations separate from inferences.32- Trace the failing value, state, or resource backward to where its invariant first became false.33- Read callers, middleware, initialization, build constraints, configuration, and external dependencies before declaring a local line defective.34- Compare with a nearby working path when it shares the same contract.35- Escalate diagnostics from focused logs/tests to race, trace, profiles, or a debugger according to the symptom. Read [references/diagnostic-tools.md](references/diagnostic-tools.md) when basic evidence is insufficient.36- Do not install tools, expose endpoints, attach to processes, restart services, capture customer data, or mutate external systems without the authorization required for that action.3738## Root-Cause Standard3940A root-cause explanation should connect:41421. the triggering conditions;432. the first violated invariant;443. the propagation path;454. why the observed symptom follows;465. evidence that distinguishes this explanation from alternatives.4748An added nil check, retry, delay, or larger buffer is not a root cause by itself. It may still be the correct fix if the API contract says the boundary must tolerate that condition; explain why.4950## Fix and Verify5152Prefer a regression test that fails for the observed condition and passes after the fix, but do not invent an unreliable test merely to satisfy a ritual.5354After a fix:5556- rerun the exact reproduction;57- run affected tests and static analysis;58- add race, integration, cross-platform, or profile comparison checks as warranted;59- remove temporary instrumentation or clearly identify intentional observability changes;60- review whether the same invalid state can enter through another path.6162## Deliverable6364Report reproduction status, evidence collected, confirmed root cause or ranked remaining hypotheses, the scope of any fix, verification results, and uncertainty. Distinguish unavailable evidence from evidence that disproves a hypothesis.
reagin