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.

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.