errors

errors

A Go library for working with errors that supports structured context.

Getting started

Add the dependency with:

go get github.com/sirkon/errors@latest

See a minimal setup and usage example in internal/example/main.go.

Features and goals

• Errors are considered to be processes, not values. This means you should not compare two errors as you would not try to compare two processes and do not use errors.New and errors.Newf to create sentinel errors. There are errors.NewSentinel and errors.NewSentinelf for this.
• Almost drop-in replacement for the standard errors package.
• Avoid the inconsistency in the standard library where you use errors.New but fmt.Errorf.
• Real first class error wrapping support with errors.Wrap and errors.Wrapf.
• Structured context support, so you don’t have to log the same error at multiple layers just to add details — simply attach context to the error and the extra data will be rendered by default.
• Optional inclusion of the file:line location where the error was created/handled. See loc.go.

Usage examples

// You can create errors and attach context to it.
return errors.New("unexpected name").Str("expected", expected).Str("actual", name)

// You can wrap and add context.
if err != nil {
return errors.Wrap(err, "do something").Int("int", intVal).Str("str", strVal)
}

// Sometimes text annotation doesn't make a sense, but some context info does.
if err != nil {
return errors.Just(err).Int("int", intVal)
}

Performance

The benchmark produced the following numbers:

As you see, this library has both faster and doesn't degrade at the scale.

Now, pipeline benchmarking. We get an error, we annotate it, we log it. Four cases in here:

1. Development mode logging with slog.
2. Production mode logging with slog.
3. We log at every step of stdlib's error processing to mimic this library' behavior.
4. We just put everything in text format to deliver the context.

Here outputs look like

Dev.

{
  "time": "2026-02-21T23:24:48.261254+03:00",
  "level": "ERROR",
  "msg": "log error with tree structured context",
  "err": "check error: this is an error",
  "@err": {
    "NEW: this is an error": {
      "bytes": "AQID",
      "text-bytes": "Hello World!"
    },
    "WRAP: check error": {
      "count": 333,
      "is-wrap-layer": true
    },
    "CTX": {
      "pi": 3.141592653589793,
      "e": 2.718281828459045
    }
  }
}

Prod.

{
  "time": "2026-02-21T23:24:48.261709+03:00",
  "level": "ERROR",
  "msg": "log error with flat structured context",
  "err": "check error: this is an error",
  "@err": {
    "bytes": "AQID",
    "text-bytes": "Hello World!",
    "count": 333,
    "is-wrap-layer": true,
    "pi": 3.141592653589793,
    "e": 2.718281828459045
  }
}

fmt.Errorf with the logging at every step

{
  "time": "2026-02-21T23:34:53.317258+03:00",
  "level": "ERROR",
  "msg": "failed to do something 1",
  "err": "this is an error",
  "bytes": "AQID",
  "text-bytes": "Hello World!"
}
{
  "time": "2026-02-21T23:34:53.317293+03:00",
  "level": "ERROR",
  "msg": "failed to check error",
  "err": "this is an error",
  "count": 333,
  "is-wrap-layer": true
}
{
  "time": "2026-02-21T23:34:53.317299+03:00",
  "level": "ERROR",
  "msg": "got an error",
  "err": "check error: this is an error",
  "pi": 3.141592653589793,
  "e": 2.718281828459045
}

fmt.Errorf with text format.

{
  "time": "2026-02-21T23:29:56.447285+03:00",
  "level": "ERROR",
  "msg": "failed to do something 1",
  "err": "context pi[3.141592653589793] e[2.718281828459045]: check error count[333] is-wrap-layer[true]: this is an error bytes[[1 2 3]] text-bytes[Hello World!]"
}

We disabled location logging in both logger and this library (which makes it at every New, Wrap and Just).

As you can see, fmt.Errorf with text format is just 14% faster than Prod flat context solution being worse in every other way possible. Multiple logging is slow and just an antipattern.

Appendix.

This is how full Dev output looks like:

{
  "time": "2026-02-21T23:58:48.542593+03:00",
  "level": "ERROR",
  "msg": "log error with tree structured context",
  "err": "check error: this is an error",
  "@err": {
    "NEW: this is an error": {
      "@location": "/Users/d.cheremisov/Sources/mine/errors/internal/example/example.go:16",
      "bytes": "AQID",
      "text-bytes": "Hello World!"
    },
    "WRAP: check error": {
      "@location": "/Users/d.cheremisov/Sources/mine/errors/internal/example/example.go:19",
      "count": 333,
      "is-wrap-layer": true
    },
    "CTX": {
      "@location": "/Users/d.cheremisov/Sources/mine/errors/internal/example/example.go:22",
      "pi": 3.141592653589793,
      "e": 2.718281828459045
    }
  }
}