go-errors: Structured, contextual error handling for Go

an AGILira library

go-errors is a fast, structured, and context-aware error handling library for Go. Built for Styx, it includes error codes, stack traces, user messages, and JSON support — with zero overhead.

Features

• Structured error type: code, message, context, cause, severity
• Stacktrace support (optional, lightweight)
• User and technical messages
• Custom error codes (user-defined)
• JSON serialization for API/microservices
• Retryable and interface-based error handling
• Helpers for wrapping, root cause, code search
• 100% Go standard library, no external dependencies
• Modular, fully tested, high coverage

Installation

go get github.com/agilira/go-errors

Quick Example

import "github.com/agilira/go-errors"

const ErrCodeValidation = "VALIDATION_ERROR"

func validateUser(username string) error {
    if username == "" {
        return errors.New(ErrCodeValidation, "Username is required").WithUserMessage("Please enter a username.")
    }
    return nil
}

JSON Output

Errors automatically serialize to structured JSON:

err := errors.New("VALIDATION_ERROR", "Email format invalid").
    WithUserMessage("Please enter a valid email address").
    WithContext("field", "email").
    WithSeverity("warning")

jsonData, _ := json.Marshal(err)
// Output: {"code":"VALIDATION_ERROR","message":"Email format invalid","user_msg":"Please enter a valid email address","context":{"field":"email"},"severity":"warning","timestamp":"2025-01-27T10:30:00Z",...}

Testing & Coverage

Run all tests:

go test -v ./...

Check coverage:

go test -cover ./...

• Write tests for all custom error codes and logic in your application.
• Use table-driven tests for error scenarios.
• Aim for high coverage to ensure reliability.

Documentation

Comprehensive documentation is available in the docs folder:

• API Reference - Complete API documentation with examples
• Usage Guide - Getting started and basic usage patterns
• Best Practices - Production-ready patterns and recommendations
• Integration Guide - Migration guide and advanced integration patterns

---

go-errors • an AGILira library