Errata - Structured error handling for Elixir

This looks interesting! Question: the docs say

Using the create/1 macro, on the other hand, fills in the :env field of the error struct with information from the current __ENV__ struct and the current stacktrace.

I thought that was only available in rescue blocks since System.stacktrace/0 was deprecated years ago - for performance reasons IIRC. Are there any performance implications of using the create/1 macro?

Hi @nathanl,

The create/1 macro uses Process.info(self(), :current_stacktrace) to fill in the stacktrace. I’m not sure about the efficiency of this function, but I would venture to say that if you are using create/1 for creating Errata errors in your codebase then it would probably not be on the critical path and would not affect overall system performance to any appreciable degree.

Yeah, hopefully you’re not creating errors in a tight loop.

Errata 0.9.0 is out, and it’s a sizable release — some new conveniences, sharper defaults, and a thorough documentation overhaul.

New functions

• Errata.create/2 — create an error of any type while still capturing the call-site environment, without having to require each error module. Since you already require Errata to use the guards, you can just alias your error modules and write:

  require Errata
  alias MyApp.Orders.OrderNotFound
  
  Errata.create(OrderNotFound, reason: :not_found, context: %{order_id: id})
  

• Errata.to_map/1 — convert any Errata error to a plain, JSON-encodable map without needing to know its specific module. Handy at a system boundary (e.g. a Phoenix fallback controller) that handles many error types uniformly.

• Errata.display_message/1 — the bare, human-readable message intended for end users, as distinct from Exception.message/1, which combines the message and :reason for logs and raised-exception output.

Sharper defaults

• Creating an error with an unrecognized or misspelled key (say, reasn: instead of reason:) now raises an ArgumentError instead of silently dropping it. This is the one breaking change in 0.9.0 — see Upgrading below.

Fixes

• Serialized errors are cleaner: JSON output no longer leaks the Elixir. prefix on module names, and env.file_line no longer has a stray trailing colon.

Docs & tooling

• The guide has been reorganized around a single running example (an Orders bounded context), with clearer guidance on choosing between domain, infrastructure, and general errors, and on when to use a distinct error type vs. a :reason.
• There’s now a CI pipeline that runs the test suite across Elixir 1.15–1.18 and OTP 25–27, plus formatting, Credo, Dialyzer, and docs checks.

Upgrading

Bump your dependency to:

{:errata, "~> 0.9.0"}

The only breaking change is the stricter param validation. If you were (perhaps unknowingly) relying on extra keys being ignored, you’ll now get a clear ArgumentError — in practice this usually just surfaces a typo.

Thanks to everyone who’s given Errata a try and shared feedback; it’s genuinely shaped this release. More is always welcome.

Quick update for anyone following along: Errata has reached 1.0.0 — its first stable, production-ready release, with the public API now covered by Semantic Versioning.

Since this thread it has grown a fair bit: error wrapping/chaining (a :cause field), context enrichment as errors propagate, declared-and-validated :reasons, error reporting via structured logging and telemetry, and HTTP-status mapping by error kind — alongside a thorough documentation pass.

I’ve written up the full 1.0.0 picture, with examples, in a dedicated thread:

Thanks to everyone who’s tried Errata and shared feedback — it genuinely shaped the road to 1.0.