secmon-lab/goerr-error-handling

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