errdef

errdef

errdef separates Go errors into Definitions and Error instances, making them typed, structured, and uniform. It integrates cleanly with the standard ecosystem — errors.Is / errors.As, fmt.Formatter, json.Marshaler, and slog.LogValuer — while adding fields, stack traces, and flexible error composition.

Status: The core API is stable, but minor breaking changes may occur before v1.0.0.

Table of Contents

• Getting Started
• Features
  • Error Constructors
  • Error Inspection
  • Detailed Error Formatting
  • Source Code Snippets
  • JSON Marshaling
  • Structured Logging (slog)
  • Field Constructors
  • Field Extractors
  • Free-Form Details
  • Context Integration
  • Redaction
  • Joining Errors
  • Panic Recovery
  • Error Resolution
  • Error Deserialization
  • Ecosystem Integration
  • Built-in Options
• Examples
• Performance
• Library Comparison

Getting Started

go get github.com/shiwano/errdef

package main

import (
    "context"
    "errors"
    "fmt"

    "github.com/shiwano/errdef"
)

var (
    // Reusable error definition (sentinel-like, extensible).
    ErrNotFound = errdef.Define("not_found", errdef.HTTPStatus(404))

    // Type-safe field (constructor + extractor pair).
    UserID, UserIDFrom = errdef.DefineField[string]("user_id")
)

func findUser(ctx context.Context, id string) error {
    // Create an error; attach typed fields as needed.
    return ErrNotFound.With(ctx, UserID(id)).New("user not found")
}

func main() {
    err := findUser(context.TODO(), "u123")

    // Standard errors.Is still works.
    if errors.Is(err, ErrNotFound) {
        fmt.Println("user not found")
    }

    // Extract fields in a type-safe way.
    if userID, ok := UserIDFrom(err); ok {
        fmt.Println("user id:", userID)
    }
}

Note: Both errors.Is and field extractors compare identities, not string names. Each Define or DefineField call creates a unique identity, even with identical strings. Use unique names throughout your application to avoid confusion.

// Different definitions with the same kind string
ErrNotFound1 := errdef.Define("not_found")
ErrNotFound2 := errdef.Define("not_found")

err1 := ErrNotFound1.New("not found")
errors.Is(err1, ErrNotFound1) // true
errors.Is(err1, ErrNotFound2) // false - different definition

// Different field definitions with the same name
UserID1, UserID1From := errdef.DefineField[string]("user_id")
UserID2, UserID2From := errdef.DefineField[string]("user_id")

err2 := ErrNotFound1.WithOptions(UserID1("u123")).New("not found")
_, ok := UserID1From(err2) // ok: true
_, ok = UserID2From(err2)  // ok: false - different field

Features

Error Constructors

Choose how to construct an error depending on whether you create a new one or keep a cause.

• New(msg): Create a new error.
• Errorf(fmt, ...): Create with a formatted message.
• Wrap(cause): Wrap and keep the cause (errors.Is(err, cause) stays true).
• Wrapf(cause, fmt, ...): Wrap with a cause and a formatted message.
• Join(causes...): Join multiple causes (errors.Is(err, cause) stays true).

// New / Errorf
e1 := ErrNotFound.New("user not found")
e2 := ErrNotFound.Errorf("user %s not found", "u123")

// Wrap / Wrapf (keep the cause)
e3 := ErrNotFound.Wrap(sql.ErrNoRows)
e4 := ErrNotFound.Wrapf(sql.ErrNoRows, "lookup failed: %s", "u123")

errors.Is(e3, sql.ErrNoRows) // true
errors.Is(e4, sql.ErrNoRows) // true

// Join (keep multiple causes)
e5 := ErrNotFound.Join(sql.ErrNoRows, sql.ErrConnDone)

errors.Is(e5, sql.ErrNoRows)   // true
errors.Is(e5, sql.ErrConnDone) // true

Attaching Additional Options

• With(ctx, ...opts): Requires ctx. Use when options need request-scoped data.
• WithOptions(...opts): No ctx. Use for context-independent options.

// Context-aware (requires ctx)
e1 := ErrNotFound.With(context.TODO(), UserID("u123")).New("user not found")

// Context-free (no ctx)
e2 := ErrNotFound.WithOptions(UserID("u123")).New("user not found")

Error Inspection

You can inspect the kind, fields, stack trace, or causes from both errdef.Definition and any errdef.Error in the error chain.

if kind, ok := errdef.KindFrom(err); ok {
    fmt.Println("kind:", kind)
}

if fields, ok := errdef.FieldsFrom(err); ok {
    fmt.Println("fields:", fields)
}

if stack, ok := errdef.StackFrom(err); ok {
    fmt.Println("stack:", stack)
}

if causes, ok := errdef.UnwrapTreeFrom(err); ok {
    fmt.Println("causes:", causes)
}

Detailed Error Formatting

Using the %+v format specifier will print the error message, kind, fields, stack trace, and any wrapped errors.

err := findUser(ctx, "u-123")
fmt.Printf("%+v\n", err)

Example Output:

user not found
---
kind: not_found
fields:
  http_status: 404
  user_id: u-123
stack:
  main.findUser
    /path/to/your/project/main.go:23
  main.main
    /path/to/your/project/main.go:35
  runtime.main
    /usr/local/go/src/runtime/proc.go:250
causes: (1 error)
  [1] record not found
      ---
      stack:
        ...

Source Code Snippets

You can enhance stack traces with source code snippets using the StackSource(around, depth) option. This displays around lines before and after each stack frame, with depth controlling how many frames to show (use -1 for all frames, 0 to disable with zero overhead).

var ErrNotFound = errdef.Define("not_found", errdef.StackSource(3, 1))
err := findUser(ctx, "u-123")
fmt.Printf("%+v\n", err)

Example Output:

user not found
---
kind: not_found
fields:
  http_status: 404
  user_id: u-123
stack:
  main.findUser
    /path/to/your/project/main.go:23
      20: var ErrNotFound = errdef.Define("not_found", errdef.StackSource(3, 1))
      21:
      22: func findUser(ctx context.Context, id string) error {
    > 23:     return ErrNotFound.With(ctx, UserID(id)).New("user not found")
      24: }
      25:
      26: func main() {
  main.main
    /path/to/your/project/main.go:35
  runtime.main
    /usr/local/go/src/runtime/proc.go:250
causes: (1 error)
  [1] record not found

Note: Source code is read from disk at runtime only when printing errors with %+v format. If source files are unavailable (e.g., in production binaries without deployed source files), it shows only the stack trace. The implementation is designed to minimize overhead.

JSON Marshaling

errdef.Error implements json.Marshaler to produce structured JSON output.

Example Output:

{
  "message": "user not found",
  "kind": "not_found",
  "fields": {
    "http_status": 404,
    "user_id": "u-123"
  },
  "stack": [
    { "function":"main.findUser","file":"/path/to/your/project/main.go","line":23 },
    { "function":"main.main","file":"/path/to/your/project/main.go","line":35 },
    { "function":"runtime.main","file":"/usr/local/go/src/runtime/proc.go","line":250 }
  ],
  "causes": [
    { "message": "record not found", "stack":[] }
  ]
}

Note: If multiple fields have the same name, the last one in insertion order will be used in the JSON output.

Structured Logging (slog)

errdef.Error implements slog.LogValuer out-of-the-box to provide structured logging with zero configuration.

slog.Error("failed to find user", "error", err)

Example Output:

{
  "level": "ERROR",
  "msg": "failed to find user",
  "error": {
    "message": "user not found",
    "kind": "not_found",
    "fields": {
      "http_status": 404,
      "user_id": "u-123"
    },
    "origin": {
      "file": "/path/to/your/project/main.go",
      "line": 23,
      "func": "main.findUser"
    }
  }
}

Note: If multiple fields have the same name, the last one in insertion order will be used in the log output.

By default, the slog output keeps stack traces concise (showing only the error origin) and omits the causes tree to avoid excessive verbosity. If you need more detailed information, such as full stack traces or the complete causes tree, you can use the following methods:

• Log the full stack trace: The Stack type also implements slog.LogValuer.

  stack, _ := errdef.StackFrom(err)
  slog.Error("failed to find user", "stack", stack)
  

• Log the full causes tree: The Node type also implements slog.LogValuer.

  causes, _ := errdef.UnwrapTreeFrom(err)
  slog.Error("failed to find user", "causes", causes)
  

Field Constructors

The field constructor can be chained with methods like WithValue or WithValueFunc to create new, simplified constructors. This is useful for creating options with predefined or dynamically generated values.

var (
    errorCode, _            = errdef.DefineField[int]("error_code")
    ErrorCodeAmountTooLarge = errorCode.WithValue(2002)

    errorUniqueID, _ = errdef.DefineField[string]("error_unique_id")
    ErrorUniqueID    = errorUniqueID.WithValueFunc(func() string {
        return generateRandomID()
    })
)

err := ErrPaymentFailed.WithOptions(
    ErrorCodeAmountTooLarge(),
    ErrorUniqueID(),
).New("amount too large")

Field Extractors

The field extractor provides several helper methods for retrieving values from an error instance, especially for handling cases where a field might not exist.

errWithCode := ErrPaymentFailed.New("payment failed")
errWithoutCode := ErrNotFound.New("not found")

code, ok := ErrorCodeFrom(errWithCode)
// code: 2001, ok: true

defaultCode := ErrorCodeFrom.OrDefault(errWithoutCode, 9999)
// defaultCode: 9999

fallbackCode := ErrorCodeFrom.OrFallback(errWithoutCode, func(err error) int {
    return 10000
})
// fallbackCode: 10000

codeWithDefault := ErrorCodeFrom.WithDefault(9999)
// codeWithDefault(errWithCode)    -> 2001
// codeWithDefault(errWithoutCode) -> 9999

Note: Extractors follow the same rules as errors.As. They search the error chain and extract the value from the first matching errdef.Error, then stop searching. If you need inner fields at the outer layer, prefer explicitly copying the needed fields when wrapping.

Free-Form Details

You can attach free-form diagnostic details to an error under the "details" field.

err := ErrNotFound.With(
  errdef.Details{"tenant_id": 1, "user_ids": []int{1,2,4}},
).Wrap(err)

details := errdef.DetailsFrom.OrZero(err)
// details: errdef.Details{
//   "tenant_id": 1,
//   "user_ids": []int{1,2,4},
// }

Note: Details is derived from a map[string]any type and implements Option, allowing you to attach arbitrary key-value pairs.

Context Integration

You can use context.Context to automatically attach request-scoped information to your errors.

func tracingMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Attach the TraceID option to the context.
        ctx := errdef.ContextWithOptions(
            r.Context(),
            errdef.TraceID(r.Header.Get("X-Request-ID")),
        )
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

var ErrRateLimited = errdef.Define("rate_limited", errdef.HTTPStatus(429))

func someHandler(ctx context.Context) error {
    // The TraceID option is automatically attached from the context.
    return ErrRateLimited.With(ctx).New("too many requests")
}

Redaction

Wrap secrets (tokens, emails, IDs, etc.) with Redacted[T] to ensure they always render as "[REDACTED]" in logs and serialized output (fmt, json, slog, encoding). The original value remains accessible via .Value() for internal use.

var UserEmail, UserEmailFrom = errdef.DefineField[errdef.Redacted[string]]("user_email")

err := ErrInvalidArgument.With(
  UserEmail(errdef.Redact("[email protected]")),
).Wrap(err)

// fmt.Printf("%+v\n", err): user_email: [REDACTED]
// log/slog prints         : user_email="[REDACTED]"
// json.Marshal(err)       : { "user_email": "[REDACTED]" }
// internal access         : email, _ := UserEmailFrom(err); _ = email.Value()

Joining Errors

You can join multiple errors into one using the Join method on a Definition.

var (
  ErrLeft  = errdef.Define("left")
  ErrRight = errdef.Define("right")
  ErrTop   = errdef.Define("top")
)

l := ErrLeft.New("L")
r := ErrRight.New("R")
err := ErrTop.Join(l, r)
causes := err.(errdef.Error).Unwrap()
// causes: [l, r]

Panic Recovery

errdef provides a convenient way to convert panics into structured errors, ensuring that even unexpected failures are handled consistently.

var ErrPanic = errdef.Define("panic", errdef.HTTPStatus(500))

func processRequest(w http.ResponseWriter, r *http.Request) error {
    err := ErrPanic.Recover(func() error {
        maybePanic()
        return nil
    })
    if errors.Is(err, ErrPanic) {
        slog.Warn("a panic was captured")
        // Perform cleanup or additional logging
    }
    return err
}

if err := processRequest(w, r); err != nil {
    var pe errdef.PanicError
    if errors.As(err, &pe) {
        slog.Error("a panic occurred", "panic_value", pe.PanicValue())
    }
    // ...
}

Error Resolution

For advanced use cases like mapping error codes from external APIs, use a Resolver.

import (
    "github.com/shiwano/errdef"
    "github.com/shiwano/errdef/resolver"
)

var (
    ErrStripeCardDeclined = errdef.Define("card_declined", errdef.HTTPStatus(400))
    ErrStripeRateLimit    = errdef.Define("rate_limit", errdef.HTTPStatus(429))
    ErrStripeUnhandled    = errdef.Define("stripe_unhandled", errdef.HTTPStatus(500))

    // Order defines priority (first-wins).
    ErrStripe = resolver.New(
        ErrStripeCardDeclined,
        ErrStripeRateLimit,
    ).WithDefault(ErrStripeUnhandled) // Remove if you want strict matching.
)

func handleStripeError(code, msg string) error {
    return ErrStripe.ResolveKindOrDefault(errdef.Kind(code)).New(msg)
}

func handleStripeHTTPError(statusCode int, msg string) error {
    return ErrStripe.ResolveFieldOrDefault(errdef.HTTPStatus.Key(), statusCode).New(msg)
}

Note: If multiple definitions have the same Kind or field value, the first one in the resolver's definition order will be used.

Error Deserialization

The errdef/unmarshaler package allows you to deserialize errdef.Error instances from JSON or other formats. Use a Resolver to map kind strings to error definitions, and the unmarshaler will restore typed errors with their fields and stack traces.

package main

import (
    "encoding/json"
    "fmt"
    "io"

    "github.com/shiwano/errdef"
    "github.com/shiwano/errdef/resolver"
    "github.com/shiwano/errdef/unmarshaler"
)

var (
    ErrNotFound        = errdef.Define("not_found")
    UserID, UserIDFrom = errdef.DefineField[string]("user_id")
)

func main() {
    // Serialize an errdef.Error to JSON
    original := ErrNotFound.WithOptions(UserID("u123")).Wrapf(io.EOF, "user not found")
    data, _ := json.Marshal(original)

    // Deserialize JSON back into an errdef.Error
    r := resolver.New(ErrNotFound)
    u := unmarshaler.NewJSON(r,
        unmarshaler.WithBuiltinFields(),
        unmarshaler.WithStandardSentinelErrors(),
    )
    restored, _ := u.Unmarshal(data)

    fmt.Println(restored.Error())                 // "user not found"
    fmt.Println(UserIDFrom.OrZero(restored))      // "u123"
    fmt.Println(errors.Is(restored, ErrNotFound)) // true
    fmt.Println(errors.Is(restored, io.EOF))      // true
}

Note: The unmarshaler package is designed to work with any serialization format, not just JSON. You can implement custom Decoder functions for formats like Protocol Buffers, XML, MessagePack, or any proprietary format.

// Custom decoder for your format
func protoDecoder(msg *ErrorProto) (*unmarshaler.DecodedData, error) {
    return convertToDecodedData(msg), nil
}

// Use it with the unmarshaler
u := unmarshaler.New(resolver, protoDecoder)
msg := createProtoMessage() // *ErrorProto
restored, _ := u.Unmarshal(msg) // Type-safe: accepts *ErrorProto by generics

For a complete example with Protocol Buffers including marshal functions and full round-trip demonstration, see examples/protobuf.

Ecosystem Integration

errdef is designed to work seamlessly with the broader Go ecosystem.

• Structured Logging:
  • slog: Implements slog.LogValuer for rich, structured logs out-of-the-box.
  • zap: Compatible with zap via helper functions. See examples/zap.
  • zerolog: Compatible with zerolog via helper functions. See examples/zerolog.
• Error Reporting Services:
  • Sentry: Compatible with the Sentry Go SDK by implementing the StackTracer interface. See examples/sentry.
  • Google Cloud Error Reporting: Compatible with Google Cloud Error Reporting by implementing the DebugStacker interface. See examples/gcloud_error_reporting.
• Legacy Error Handling:
  • pkg/errors: Supports interoperability with pkg/errors by implementing the causer interface.

Built-in Options

Examples

• HTTP API Server - Error handling in REST APIs
• Protocol Buffers - Custom serialization with protobuf
• Sentry - Error reporting with automatic field extraction
• Google Cloud Error Reporting - Integration with Google Cloud Error Reporting
• zap - Structured logging integration with zap
• zerolog - Structured logging integration with zerolog

Performance

Last updated: 2025-10-18

errdef adds structured error handling on top of Go's standard library. Here are the key performance metrics:

Note: Benchmarked on Apple M1 Pro, Go 1.25 (stack depth: 32)

How to Run the Benchmarks

GOMAXPROCS=1 go test -bench=. -benchmem -benchtime=3s ./...

Performance Best Practices

In practice, error handling is rarely the bottleneck. Focus on correctness first, then optimize if profiling shows that error creation is a significant cost.

1. Default is fine for most cases: The ~303 ns overhead is negligible unless you're creating thousands of errors per second.

2. Disable stack traces in hot paths: Stack trace capture takes ~275 ns per error. Use NoTrace() in tight loops or high-frequency code paths where errors are common:

   // ✅ Hot paths (loops, frequently called functions)
   var ErrValidation = errdef.Define("validation", errdef.NoTrace())
   for _, item := range items {
       if err := validate(item); err != nil {
           return ErrValidation.Wrap(err) // Fast: ~28 ns, 80 B
       }
   }
   
   // ❌ API boundaries, critical errors (keep stack traces!)
   var ErrDatabaseFailure = errdef.Define("db_failure") // ~303 ns, 336 B
   

3. Minimize dynamic fields: Using With() or WithOptions() adds ~202 ns base overhead plus ~59 ns per field. For hot paths where fields are constant, prefer defining errors with fields upfront:

   // ✅ Attach fields to definition upfront
   var ErrInvalidInput = errdef.Define("invalid_input", errdef.HTTPStatus(400), errdef.NoTrace())
   for _, input := range inputs {
       if !input.IsValid() {
           return ErrInvalidInput.New("invalid") // Fast: ~28 ns, 80 B
       }
   }
   
   // ❌ Attach fields dynamically in hot path
   var ErrInvalidInput = errdef.Define("invalid_input", errdef.NoTrace())
   for _, input := range inputs {
       if !input.IsValid() {
           return ErrInvalidInput.WithOptions(errdef.HTTPStatus(400)).New("invalid") // ~230 ns, 640 B
       }
   }
   

4. Limit stack depth: For hot paths where you still want to capture the error origin, use StackDepth(1) to keep just the first frame:

   // ✅ Capture only the immediate origin
   var ErrDBQuery = errdef.Define("db_query", errdef.StackDepth(1))
   if err := db.Query(...); err != nil {
       return ErrDBQuery.Wrap(err) // Fast: ~177 ns, 88 B
   }
   
   // ❌ Keep full stack trace (default depth: 32)
   var ErrDBQuery = errdef.Define("db_query")
   if err := db.Query(...); err != nil {
       return ErrDBQuery.Wrap(err) // ~289 ns, 336 B
   }
   

Additional Operations

Other operations also have measurable overhead:

Library Comparison

Last updated: 2025-10-07

If you spot inaccuracies or want another library included, please open an issue or PR.

Comparison Table

Quick Notes

• pkg/errors: A historical library that added stack trace functionality, but is now archived.
• cockroachdb/errors: Specializes in distributed systems and has a very powerful Protobuf serialization/deserialization feature.
• eris: Provides good stack trace formatting but lacks structured field attachment feature.
• errorx / merry v2: Although not type-safe, they provide a feature to attach information to errors in a simple key-value format.
• errdef: Features a design that separates Definitions from Instances, enabling type-safe fields, native slog integration, and full JSON round-trip capabilities.

Contributing

Contributions are welcome! Feel free to send issues or pull requests.

License

This project is licensed under the MIT License.