go-error-handling_skill

Overview

This skill teaches idiomatic error handling patterns in Go, covering wrapping with context, custom error types, sentinel errors, and inspection with errors.Is and errors.As. It focuses on practical conventions you can apply across packages to make errors diagnosable and maintainable. Use it to avoid common pitfalls like ignored errors, lost error types, and double-wrapping.

How this skill works

The skill explains when to wrap errors vs return them, how to add context using fmt.Errorf with %w, and how to define and return custom error types. It shows how to declare package-level sentinel errors and how to inspect errors with errors.Is for sentinel values and errors.As for typed errors. The guidance highlights wrapping at package boundaries and avoiding wrapping nil or wrapping the same error multiple times.

When to use it

• When you need to add context crossing a package or API boundary
• When you must represent domain-specific failures with structured data
• When callers need to distinguish specific error conditions (not found, access denied)
• When writing libraries that other packages will inspect or handle
• When debugging or instrumenting failures to preserve original cause

Best practices

• Always check err != nil; never ignore errors
• Wrap with fmt.Errorf("...: %w", err) to preserve the original type
• Wrap at package boundaries; return internal errors unchanged when internal
• Use sentinel package-level errors for simple, comparable conditions
• Use custom error types with Error() and use errors.As to extract fields
• Avoid double-wrapping and never wrap a nil error

Example use cases

• Repository.Find returns ErrNotFound; service layers use errors.Is to handle missing records
• Validation returns a ValidationError type so HTTP handlers can extract field-level details
• A CLI wraps low-level file errors with operation context before returning to main
• A library exposes sentinel errors so callers can switch behavior on known conditions
• Middleware logs errors and wraps them with user-friendly messages at API boundaries