go-errors is a fast, structured, and context-aware error handling library for Go. Originally built for Orpheus, it provides error codes, stack traces, user messages, and JSON support with near-zero overhead through Timecache integration.
CI Security Go Report Card Coverage pkg.go.dev
Features • Performance • Quick Start • JSON Output • Testing & Coverage • Documentation
- 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
- Modular, fully tested, high coverage
go-errors is designed for Go 1.23+ environments and follows Long-Term Support guidelines to ensure consistent performance across production deployments.
AMD Ryzen 5 7520U with Radeon Graphics
BenchmarkNew-8 12971414 86.61 ns/op 208 B/op 2 allocs/op
BenchmarkNewWithField-8 12536019 87.98 ns/op 208 B/op 2 allocs/op
BenchmarkNewWithContext-8 20815206 57.17 ns/op 160 B/op 1 allocs/op
BenchmarkWrap-8 2111182 558.0 ns/op 264 B/op 4 allocs/op
BenchmarkMethodChaining-8 5201632 220.8 ns/op 504 B/op 3 allocs/op
BenchmarkHasCode-8 325451757 3.66 ns/op 0 B/op 0 allocs/op
BenchmarkRootCause-8 144666518 8.18 ns/op 0 B/op 0 allocs/op
BenchmarkMarshalJSON-8 449632 2603 ns/op 568 B/op 7 allocs/op
Reproduce benchmarks:
go test -bench=. -benchmemgo get github.com/agilira/go-errors
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 }
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",...}
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.
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