Errata - Structured error handling for Elixir

News Announcing
, , , , , ,
5

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. :warning: 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.

2 Likes