errors

errors

Semantic and traceable error management for the go-kit ecosystem. Defines failure identity through stable, transport-agnostic error codes, structured context, and cause chaining.

Part of the nochebuenadev/go-kit micro-lib collection.

Features

• Stable, transport-agnostic error codes — no coupling to HTTP, gRPC, or any protocol
• Structured context (key-value metadata) attached to each error for tracing and logging
• Immutable builder API — WithContext and WithError return new instances, safe for package-level reuse
• Full errors.Is / errors.As traversal via Unwrap
• JSON serialization out of the box for API responses
• Zero external dependencies
• Exported Error interface for loose coupling between consumers

Installation

go get code.nochebuena.dev/go/errors

Requires Go 1.21 or later.

Quick start

import "code.nochebuena.dev/go/errors"

// Create a typed error.
err := errors.New(errors.ErrInvalidInput, "username is required")
fmt.Println(err.Error())
// INVALID_ARGUMENT: username is required

// Wrap an existing error and attach context.
err = errors.Wrap(errors.ErrInternal, "failed to save user", originalErr).
    WithContext("user_id", 42).
    WithContext("operation", "create")

fmt.Println(err.Detailed())
// code: INTERNAL_ERROR | message: failed to save user | Cause: ... | context: map[operation:create user_id:42]

// Coerce any error into the canonical type.
typed := errors.From(someErr)
fmt.Println(typed.GetCode()) // INTERNAL_ERROR (if someErr is not already an *errors.Err)

Constructors

Primary constructors

Shorthand helpers

All shorthand helpers accept a fmt.Sprintf-style format string.

Builder methods

Both methods return a new *Err — the original is never modified.

Error codes

Mapping these codes to protocol-specific representations (HTTP status codes, gRPC codes, etc.) is the responsibility of the transport layer.

Environment variables

This package does not read any environment variables.

Interfaces

Error

The canonical interface consumers should depend on. Accepting Error rather than *Err prevents coupling to the concrete implementation.

type Error interface {
    error                         // Error() string
    GetCode() string              // machine-readable error code
    GetContext() map[string]any   // structured metadata, always non-nil
    Detailed() string             // verbose representation for logging
}

Usage in consumers:

// In a logging or middleware layer — no import of *Err needed.
func logError(err errors.Error) {
    log.Printf("code=%s context=%v msg=%s", err.GetCode(), err.GetContext(), err.Error())
}

The logz micro-lib integrates with this package through duck typing: it checks at runtime whether an error exposes GetCode() and GetContext() without importing this module directly.

Architecture

error.go        — Error interface, Err struct, constructors, builder methods, JSON marshaling
error_code.go   — ErrorCode type and the 11 predefined constants with their descriptions
doc.go          — Package-level documentation

Immutability. WithContext and WithError perform a shallow clone of the struct and a full copy of the context map before returning a new instance. This makes it safe to define package-level sentinel errors and enrich them per call site without data races.

// Safe: each call site gets its own *Err with its own context map.
var ErrUserNotFound = errors.NotFound("user not found")

func handler(userID int) error {
    return ErrUserNotFound.WithContext("user_id", userID)
}

Cause chaining. Err implements Unwrap() error, enabling standard errors.Is and errors.As traversal through the full cause chain.

JSON serialization. *Err implements json.Marshaler. The output omits context when empty.

{"code":"NOT_FOUND","message":"user not found","context":{"user_id":42}}

License

MIT License. Copyright (c) 2026 NOCHEBUENADEV. See LICENSE for details.