Solizardking/clawd-bot / .agents/skills/golang-error-handling
golang-error-handling
VerifiedIdiomatic Golang error handling — creation, wrapping with %w, errors.Is/As, errors.Join, custom error types, sentinel errors, panic/recover, the single handling rule, structured logging with slog, HTTP request logging middleware, and samber/oops for production errors. Built to make logs usable at scale with log aggregation 3rd-party tools. Apply when creating, wrapping, inspecting, or logging errors in Go code. For samber/oops specifics → See `samber/cc-skills-golang@golang-samber-oops` skill; for slog handler ecosystem → See `samber/cc-skills-golang@golang-samber-slog` skill.
Persona: You are a Go reliability engineer. You treat every error as an event that must either be handled or propagated with context — silent failures and duplicate logs are equally unacceptable.
Orchestration mode: Use ultracode for auditing error handling across a large codebase — orchestrate the five category sub-agents described in the "Parallelizing Error Handling Audits" section (creation, wrapping, single-handling rule, panic/recover, structured logging) and consolidate their findings.
Modes:
- Coding mode — writing new error handling code. Follow the best practices sequentially; optionally launch a background sub-agent to grep for violations in adjacent code (swallowed errors, log-and-return pairs) without blocking the main implementation.
- Review mode — reviewing a PR's error handling changes. Focus on the diff: check for swallowed errors, missing wrapping context, log-and-return pairs, and panic misuse. Sequential.
- Audit mode — auditing existing error handling across a codebase. Use up to 5 parallel sub-agents, each targeting an independent category (creation, wrapping, single-handling rule, panic/recover, structured logging).
Community default. A company skill that explicitly supersedes
samber/cc-skills-golang@golang-error-handlingskill takes precedence.
Go Error Handling Best Practices
This skill guides the creation of robust, idiomatic error handling in Go applications. Follow these principles to write maintainable, debuggable, and production-ready error code.
Best Practices Summary
- Returned errors MUST always be checked — NEVER discard with
_ - Errors MUST be wrapped with context using
fmt.Errorf("{context}: %w", err) - Error strings MUST be lowercase, without trailing punctuation
- Use
%winternally,%vat system boundaries to control error chain exposure - MUST use
errors.Isfor sentinel matching anderrors.As/errors.AsTypefor typed chain inspection instead of direct comparison or bare type assertions. For Go 1.26+, prefererrors.AsType[T](err)whenTimplementserror; useerrors.As(err, &target)for Go <1.26 or for non-error interface targets. - SHOULD use
errors.Join(Go 1.20+) to combine independent errors - Errors MUST be either logged OR returned, NEVER both (single handling rule)
- Use sentinel errors for expected conditions, custom types for carrying data
- NEVER use
panicfor expected error conditions — reserve for truly unrecoverable states - SHOULD use
slog(Go 1.21+) for structured error logging — notfmt.Printlnorlog.Printf - Use
samber/oopsfor production errors needing stack traces, user/tenant context, or structured attributes - Log HTTP requests with structured middleware capturing method, path, status, and duration
- Use log levels to indicate error severity
- Never expose technical errors to users — translate internal errors to user-friendly messages, log technical details separately
- Keep log grouping low-cardinality — at logging/APM boundaries, keep message templates stable and attach IDs, paths, line numbers, and counts as structured attributes. Error values may include useful operational context, but avoid putting high-cardinality data into the stable log message used for grouping.
Detailed Reference
-
Error Creation — How to create errors that tell the story: error messages should be lowercase, no punctuation, and describe what happened without prescribing action. Covers sentinel errors (one-time preallocation for performance), custom error types (for carrying rich context), and the decision table for which to use when.
-
Error Wrapping and Inspection — Why
fmt.Errorf("{context}: %w", err)beatsfmt.Errorf("{context}: %v", err)(chains vs concatenation). How to inspect chains witherrors.Is,errors.As, and Go 1.26+errors.AsTypefor type-safe error handling, anderrors.Joinfor combining independent errors. -
Error Handling Patterns and Logging — The single handling rule: errors are either logged OR returned, NEVER both (prevents duplicate logs cluttering aggregators). Panic/recover design,
samber/oopsfor production errors, andslogstructured logging integration for APM tools.
Parallelizing Error Handling Audits
When auditing error handling across a large codebase, use up to 5 parallel sub-agents (via the Agent tool) — each targets an independent error category:
- Sub-agent 1: Error creation — validate
errors.New/fmt.Errorfusage, low-cardinality messages, custom types - Sub-agent 2: Error wrapping — audit
%wvs%v, verifyerrors.Is/errors.Aspatterns - Sub-agent 3: Single handling rule — find log-and-return violations, swallowed errors, discarded errors (
_) - Sub-agent 4: Panic/recover — audit
panicusage, verify recovery at goroutine boundaries - Sub-agent 5: Structured logging — verify
slogusage at error sites, check for PII in error messages
Cross-References
- → See
samber/cc-skills-golang@golang-samber-oopsfor full samber/oops API, builder patterns, and logger integration - → See
samber/cc-skills-golang@golang-observabilityfor structured logging setup, log levels, and request logging middleware - → See
samber/cc-skills-golang@golang-safetyfor nil interface trap and nil error comparison pitfalls - → See
samber/cc-skills-golang@golang-namingfor error naming conventions (ErrNotFound, PathError) - → See
samber/cc-skills-golang@golang-continuous-integrationskill for automated AI-driven code review in CI using these guidelines
References
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |