goerr-error-handling - SKILL.md Agent Skill

name: goerr-error-handling description: Write Go error handling code using the goerr library. Use when creating errors, wrapping errors, adding context, or handling errors in Go code that uses goerr. allowed-tools: Read, Bash(go:*)

Error Handling with goerr

When writing Go error handling code, use the goerr library for enhanced errors with stack traces, contextual values, and structured logging support.

Step 1: Locate goerr documentation

First, find where goerr is installed and read its documentation:

GOERR_DIR=$(go list -m -f '{{.Dir}}' github.com/m-mizutani/goerr/v2 2>/dev/null)

If goerr is available, read the relevant documentation from $GOERR_DIR/:

README.md - Full feature overview, code examples, and API reference
docs/migration.md - Migration guide from pkg/errors, standard errors, or goerr v1
examples/ - Working example programs for each feature

Step 2: Choose the right function

Situation	Use	NOT
Create a new error	`goerr.New("msg")`	`errors.New("msg")` or `fmt.Errorf("msg")`
Wrap an existing error	`goerr.Wrap(err, "msg")`	`fmt.Errorf("msg: %w", err)`
Add context without changing message	`goerr.With(err, goerr.V("k", v))`	`goerr.Wrap(err, err.Error(), goerr.V("k", v))`
Simple key-value context	`goerr.V("key", value)`	Building context into message string
Type-safe context	`goerr.TV(typedKey, value)`	`goerr.V()` when type safety matters
Categorize errors	`goerr.T(tagValue)`	Sentinel errors for categories
Shared context across errors	`goerr.NewBuilder(opts...)`	Repeating same options everywhere
Collect multiple errors	`goerr.Append(errs, err)`	Manual slice management
Define sentinel errors	`goerr.New("msg", goerr.ID("ERR_X"))`	`errors.New("msg")`
Extract goerr.Error	`goerr.Unwrap(err)`	`errors.As(err, &goErr)`
Extract goerr.Errors	`goerr.AsErrors(err)`	`errors.As(err, &goErrs)`
Check error tag	`goerr.HasTag(err, tag)`	Manual unwrap + check

Step 3: Apply best practices

Error messages should describe what failed, not why

// Good
goerr.Wrap(err, "failed to save user")

// Bad - "why" belongs in context values
goerr.Wrap(err, fmt.Sprintf("failed to save user %s due to timeout", userID))

Use context values for structured data, not string interpolation

// Good
goerr.Wrap(err, "query failed",
    goerr.V("table", "users"),
    goerr.V("user_id", userID))

// Bad
goerr.Wrap(err, fmt.Sprintf("query on table users failed for user %s", userID))

Define typed keys at package level for critical values

var (
    UserIDKey = goerr.NewTypedKey[string]("user_id")
    CountKey  = goerr.NewTypedKey[int]("count")
)

err := goerr.New("error", goerr.TV(UserIDKey, "user123"))
if userID, ok := goerr.GetTypedValue(err, UserIDKey); ok {
    // userID is guaranteed to be string
}

Define tags and sentinel errors at package level

var (
    TagNotFound   = goerr.NewTag("not_found")
    TagValidation = goerr.NewTag("validation")
)

var (
    ErrNotFound = goerr.New("not found", goerr.ID("ERR_NOT_FOUND"))
    ErrInvalid  = goerr.New("invalid input", goerr.ID("ERR_INVALID"))
)

Use Builder for shared context in a scope

func (s *Service) process() error {
    eb := goerr.NewBuilder(
        goerr.V("user_id", s.userID),
        goerr.V("request_id", s.reqID))

    if err := s.validate(); err != nil {
        return eb.Wrap(err, "validation failed")
    }
    if err := s.save(); err != nil {
        return eb.Wrap(err, "save failed")
    }
    return nil
}

Use Unstack() for helper functions

func newDomainError(msg string, opts ...goerr.Option) *goerr.Error {
    return goerr.New(msg, opts...).Unstack()
}

Use slog integration for structured logging

logger.Error("operation failed", slog.Any("error", err))
// Automatically includes message, values, tags, and stack trace

Quick Reference

Error creation: goerr.New, goerr.Wrap, goerr.With

Options: goerr.Value / goerr.V, goerr.TypedValue / goerr.TV, goerr.Tag / goerr.T, goerr.ID

Extraction: goerr.Unwrap, goerr.AsErrors, goerr.Values, goerr.TypedValues, goerr.Tags, goerr.HasTag, goerr.GetTypedValue

Multiple errors: goerr.Join, goerr.Append, (*Errors).ErrorOrNil, (*Errors).IsEmpty, (*Errors).Len

Builder: goerr.NewBuilder, (*Builder).With, (*Builder).New, (*Builder).Wrap

Type-safe keys: goerr.NewTypedKey[T], goerr.TV, goerr.GetTypedValue

Tags: goerr.NewTag, goerr.T, goerr.HasTag, (*Error).HasTag

Stack control: (*Error).Unstack, (*Error).UnstackN