Agent skill
go-error-handling
Use when writing, reviewing, or debugging Go error handling code. Covers error wrapping, sentinel errors, custom error types, error joining, single handling, and error flow patterns. Based on Google and Uber style guides.
Install this agent skill to your Project
npx add-skill https://github.com/saisudhir14/claude-skills/tree/main/skills/go-error-handling
Metadata
Additional technical details for this skill
- tags
- golang go errors error-handling wrapping sentinel
- author
- saisudhir14
- category
- languages
SKILL.md
Go Error Handling
Comprehensive error handling patterns for production Go code.
Return Errors, Do Not Panic
Production code must avoid panics. Return errors and let callers decide how to handle them.
// Wrong
func run(args []string) {
if len(args) == 0 {
panic("an argument is required")
}
}
// Correct
func run(args []string) error {
if len(args) == 0 {
return errors.New("an argument is required")
}
return nil
}
func main() {
if err := run(os.Args[1:]); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}
}
Error Wrapping
Use %w when callers need to inspect the underlying error with errors.Is or errors.As. Use %v when you want to hide implementation details or at system boundaries.
// Preserve error chain for programmatic inspection
if err != nil {
return fmt.Errorf("load config: %w", err)
}
// Hide internal details at API boundaries
if err != nil {
return fmt.Errorf("database unavailable: %v", err)
}
Keep context succinct. Avoid phrases like "failed to" that pile up as errors propagate.
// Wrong: produces "failed to x: failed to y: failed to create store: the error"
return fmt.Errorf("failed to create new store: %w", err)
// Correct: produces "x: y: new store: the error"
return fmt.Errorf("new store: %w", err)
Joining Multiple Errors (Go 1.20+)
Use errors.Join when multiple operations can fail independently.
var (
ErrNameRequired = errors.New("name required")
ErrEmailRequired = errors.New("email required")
)
func validateUser(u User) error {
var errs []error
if u.Name == "" {
errs = append(errs, ErrNameRequired)
}
if u.Email == "" {
errs = append(errs, ErrEmailRequired)
}
return errors.Join(errs...)
}
// errors.Is works on joined errors
if err := validateUser(u); err != nil {
if errors.Is(err, ErrNameRequired) {
// matches even when joined with other errors
}
}
Error Types
Choose based on caller needs:
| Caller needs to match? | Message type | Approach |
|---|---|---|
| No | Static | errors.New("something bad") |
| No | Dynamic | fmt.Errorf("file %q not found", file) |
| Yes | Static | Exported var ErrNotFound = errors.New("not found") |
| Yes | Dynamic | Custom error type with Error() method |
Sentinel Errors and errors.Is
var (
ErrNotFound = errors.New("not found")
ErrInvalidUser = errors.New("invalid user")
)
if errors.Is(err, ErrNotFound) {
// handles ErrNotFound even when wrapped
}
var pathErr *os.PathError
if errors.As(err, &pathErr) {
fmt.Println("failed path:", pathErr.Path)
}
Error Naming
Exported error variables use Err prefix. Custom error types use Error suffix.
var ErrNotFound = errors.New("not found")
type NotFoundError struct {
Resource string
}
func (e *NotFoundError) Error() string {
return fmt.Sprintf("%s not found", e.Resource)
}
Handle Errors Once
Do not log an error and also return it. The caller will likely log it again.
// Wrong: logs and returns, causing duplicate logs
if err != nil {
log.Printf("could not get user %q: %v", id, err)
return err
}
// Correct: wrap and return, let caller decide
if err != nil {
return fmt.Errorf("get user %q: %w", id, err)
}
// Also correct: log and degrade gracefully without returning error
if err := emitMetrics(); err != nil {
log.Printf("could not emit metrics: %v", err)
}
Error Strings
Do not capitalize error strings or end with punctuation. They often appear mid-sentence in logs.
// Wrong
fmt.Errorf("Something bad happened.")
// Correct
fmt.Errorf("something bad happened")
Indent Error Flow
Keep the happy path at minimal indentation. Handle errors first.
// Wrong
if err != nil {
// error handling
} else {
// normal code
}
// Correct
if err != nil {
return err
}
// normal code continues
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
saisudhir14/claude-skills
go-project-layout
Use when starting a new Go project, organizing packages, or restructuring an existing Go codebase. Covers standard directory layout, package design, Makefile targets, Dockerfile patterns, and module setup.
saisudhir14/claude-skills
go-code-review
Use when reviewing Go code or preparing code for review. Quick-reference checklist covering naming, error handling, concurrency, testing, imports, documentation, and common pitfalls. Based on Go Wiki CodeReviewComments.
saisudhir14/claude-skills
go-concurrency
Use when writing, reviewing, or debugging concurrent Go code. Covers goroutine lifecycle management, channels, errgroup, mutexes, atomics, sync.Map, and synchronous-first design. Based on Google and Uber style guides.
saisudhir14/claude-skills
go-security
Use when writing, reviewing, or auditing Go code for security. Covers input validation, SQL injection prevention, path traversal, secrets management, cryptography, HTTP security headers, and dependency scanning.
saisudhir14/claude-skills
go-performance
Use when writing, reviewing, or optimizing Go code for performance. Covers string operations, memory allocation, preallocating slices and maps, strings.Builder, strconv, container-aware GOMAXPROCS, and runtime considerations for Go 1.25.
saisudhir14/claude-skills
go-testing
Use when writing, reviewing, or debugging Go tests and benchmarks. Covers table-driven tests, parallel execution, go-cmp, T.Context, T.Chdir, b.Loop, synctest for deterministic concurrency testing, and test failure messages.
Didn't find tool you were looking for?