errutil is a lightweight Go utility package for structured error handling.
It provides two distinct semantic styles for wrapping errors:
- Explanatory wrapping — Adds human-readable meaning or interpretation to an error, clarifying what went wrong in business or logical terms.
- Stack wrapping — Adds contextual call-path information, showing where in the call chain the error was propagated.
These two patterns serve different purposes:
- Explanatory errors are user-facing and semantic:
e.g.
"failed to load configuration: file not found" - Stack errors are developer-facing and structural:
e.g.
"InitService >> LoadConfig >> file not found"
The goal is to make error wrapping more expressive by clearly separating interpretation (:) from trace
path (>>).
Use Explain to add semantic meaning to an existing error:
err := errors.New("connection refused")
return errutil.Explain(err, "failed to connect to database")
// Output: "failed to connect to database: connection refused"Use Stack to add call-path context for debugging or tracing:
err := errors.New("file not found")
return errutil.Stack(err, "LoadConfig")
// Output: "LoadConfig >> file not found"Explain and Stack can be combined — first add a semantic explanation,
then attach call-path context:
baseErr := errors.New("file not found")
baseErr = errutil.Explain(baseErr, "failed to load configuration")
err := errutil.Stack(baseErr, "InitService")
// Output: "InitService >> failed to load configuration: file not found"This pattern preserves both semantic meaning and call-path trace, making it ideal for large or layered systems.
This project is licensed under the Apache 2.0 License. See the LICENSE file for details.