View Source Wrapping and composing errors

An error rarely travels alone. It may wrap a lower-level failure as its cause, pick up context from each layer it passes through, or stand for a whole set of errors at once. This guide covers all three.

Wrapping errors

When a lower-level subsystem or external library fails, you often want to translate that failure into a structured Errata error of your own — without discarding the original. The generated wrap/2 macro does exactly this: it creates an error (capturing the current __ENV__, like create/1) and stores the original error, exception, or value as its :cause.

The typical use is inside a rescue clause, passing __STACKTRACE__ so the original error's point of failure is preserved alongside it:

iex> require MyApp.Orders.OrderNotFound, as: OrderNotFound
iex> error =
...>   try do
...>     raise "the database connection dropped"
...>   rescue
...>     e -> OrderNotFound.wrap(e, stacktrace: __STACKTRACE__, reason: :lookup_failed)
...>   end
iex> error.reason
:lookup_failed
iex> Errata.cause(error)
%RuntimeError{message: "the database connection dropped"}

Like create/1, the wrap/2 macro must be required for each error module. The Errata.wrap/3 macro is the convenient alternative — it wraps a cause in an error of any type without a separate require for each one. Since you typically already require Errata, you can alias your error modules and call it directly:

iex> require Errata
iex> alias MyApp.Orders.OrderNotFound
iex> error = Errata.wrap(OrderNotFound, %RuntimeError{message: "boom"}, reason: :lookup_failed)
iex> error.reason
:lookup_failed
iex> Errata.cause(error)
%RuntimeError{message: "boom"}

Wrapping is for when you know what a failure means, which is why it takes the error type as an argument and always adds a layer. Where an error is on its way out of the system and anything at all can arrive, there is no type to name and rewrapping would discard a classification that is already correct; reach for Errata.to_error/2 there instead. See Wrapping versus normalizing.

The cause can be any term — another Errata error, a standard exception, or a plain value such as the reason from an {:error, reason} tuple. Retrieve the immediate cause with Errata.cause/1, or follow a chain of wrapped errors to the bottom with Errata.root_cause/1. The cause is also included when the error is serialized with to_map/1 or encoded as JSON.

For logging, Errata.format_chain/1 renders an error together with its full chain of causes:

MyApp.Orders.OrderNotFound: the requested order does not exist: :lookup_failed
Caused by: ** (RuntimeError) the database connection dropped
    (stdlib 5.2) ...

Unwrapping a wrapped error

Wrapping is worth doing because the outer error names what your code was trying to do. That is exactly why the outer message is often the least useful thing to show someone:

iex> require Errata
iex> alias MyApp.Http.RetriesExhausted
iex> error = Errata.wrap(RetriesExhausted, %RuntimeError{message: "connection refused"})
iex> Errata.display_message(error)
"the request could not be completed after 3 attempts"

"After 3 attempts" describes the retry handler's reaction. "connection refused" is the thing that actually went wrong.

A cause chain is a chain of Errata errors, the deepest of which may carry a foreign original — the exception or value your code actually caught. Two functions follow from that, and between them they cover every question:

iex> require Errata
iex> alias MyApp.Http.RetriesExhausted
iex> error = Errata.wrap(RetriesExhausted, %RuntimeError{message: "connection refused"})
iex> Errata.root_error(error) |> Errata.display_message()
"the request could not be completed after 3 attempts"
iex> Errata.root_error(error) |> Errata.cause()
%RuntimeError{message: "connection refused"}

Errata.root_error/1 walks to the deepest error, however many layers down it is, and always returns one — an error with no cause is its own root. So what comes back always has a code, a context, a classification and a display_message/1, and there is no fallback to write at the call site.

Errata.cause/1 on that error gives the foreign original, or nil when the chain is Errata errors the whole way:

iex> alias MyApp.Orders.OrderNotFound
iex> OrderNotFound.new(reason: :not_found) |> Errata.root_error() |> Errata.cause()
nil

For a log, reach for neither: Errata.format_chain/1 renders every level with the original stacktrace, which no accessor exposes.

root_cause/1 is deprecated

It returns an Errata error or a foreign value depending on how the chain ends, so a caller has to work out which it got. Errata.root_cause(error) is equivalent to Errata.cause(Errata.root_error(error)) || Errata.root_error(error); in practice you want one of the two halves, not the union.

Every accessor raises on a value that is not an Errata error. A consumer handling whatever a with chain returned does not necessarily have one, so normalize first — to_error/2 composes with all of them:

iex> Errata.to_error(:timeout) |> Errata.root_error() |> Errata.code()
nil

Why the foreign original is kept separate

Errata.cause/1 only accepts Errata errors, so a foreign value can only ever sit at the bottom of a chain, never in the middle. That bottom value is often the least useful thing there: :econnrefused has no message, no context, no code and no classification, while the error wrapping it has all four.

They are also not two views of the same fact. wrap/2 keeps the cause in :cause and copies nothing out of it, so a wrapped error's :reason and :context are untouched by what it wraps:

iex> require Errata
iex> alias MyApp.Http.RetriesExhausted
iex> error = Errata.wrap(RetriesExhausted, :econnrefused)
iex> {Errata.reason(error), Errata.context(error)}
{nil, %{}}

So the two ends of a chain answer different questions, and which you want depends on who is reading:

• Rendering, reporting, classifying — root_error/1. It is the deepest thing that still carries Errata's structure, so it is what you hand to a view, a reporter, or a retry decision.
• Diagnosing — Errata.cause/1 on the root error, for the original your code caught, or format_chain/1 for the whole picture with stacktraces.

A consumer that only reads errors

Putting those together — a module that renders errors for people, without creating any:

defmodule MyAppWeb.ErrorHelpers do
  def user_message(value) do
    value
    |> Errata.to_error()
    |> Errata.root_error()
    |> Errata.display_message()
  end
end

to_error/2 guarantees an Errata error going in, root_error/1 guarantees one coming out, so there is no clause to get wrong and no term to fall back on:

iex> MyAppWeb.ErrorHelpers.user_message(:timeout)
"an unexpected error occurred"

iex> require Errata
iex> alias MyApp.Http.RetriesExhausted
iex> MyAppWeb.ErrorHelpers.user_message(Errata.wrap(RetriesExhausted, :econnrefused))
"the request could not be completed after 3 attempts"

Note that this deliberately does not reach for Exception.message/1 on a foreign root cause. A %RuntimeError{message: "connection refused"} reads fine in a log, but on a screen it is text nobody wrote for a user — the wrapping error's display_message/1 is the one somebody did.

Enriching context as an error propagates

An error's context is usually captured where the error is created, but a structured error often travels up through several layers before it reaches a boundary — and those intermediate layers frequently know context that the creation site did not: the user_id known in one place, the request_id known in another. Errata.put_context/3 and Errata.merge_context/2 let you enrich an error's context as it propagates, without rebuilding the struct by hand.

This pairs naturally with returning errors as values through a with chain: each layer attaches what it knows and lets the error continue on its way.

iex> alias MyApp.Orders.OrderNotFound
iex> OrderNotFound.new(reason: :not_found, context: %{order_id: 42})
...> |> Errata.put_context(:user_id, 7)
...> |> Errata.merge_context(%{order_id: 99})
...> |> Errata.context()
%{order_id: 99, user_id: 7}

put_context/3 sets a single key; merge_context/2 merges a whole map, with the given values winning on any key collision. Either one initializes the context map if the error did not have one yet.

Aggregate errors

Validation produces the shape a single error struct cannot model: a request fails and there are five reasons, all of which the caller needs. Putting them in :context as a list of maps throws away everything Errata is for — each sub-failure loses its type, code, HTTP status, severity, and retryability, and becomes inert data.

Declare a type as an aggregate and it holds errors instead:

defmodule MyApp.Orders.ValidationFailed do
  use Errata.DomainError, aggregate: true, default_message: "validation failed"
end

ValidationFailed.new(errors: [email_error, age_error])

The aggregate is an ordinary Errata error — Errata.is_error/1 holds, it raises and returns in {:error, _} tuples, and it serializes through to_map/1 and the JSON encoders like anything else. Its members serialize with it, each keeping its own type, code, and redaction rules:

Errata.to_map(error).errors
#=> [%{error_type: "MyApp.Orders.EmailInvalid", code: "EMAIL_INVALID", ...},
#=>  %{error_type: "MyApp.Orders.AgeInvalid",   code: "AGE_INVALID",   ...}]

Reach the members with Errata.errors/1, which returns [] for an ordinary error so calling code never has to branch on whether it has an aggregate.

How the merge rules work

An aggregate has to answer severity/1, retryable?/1, and http_status/1 for a collection. The three merge differently, because the right answer differs:

	rule	why
severity/1	the most severe member	severities are totally ordered, so the maximum is unambiguous — and if any member is :error, the aggregate is at least :error
retryable?/1	retryable only if every member is	retrying helps only if all of it could succeed next time; one permanent failure makes the retry pointless
http_status/1	the members' status if they agree, else the aggregate's own	there is no meaningful maximum over status codes, so a "highest" would be arbitrary

An aggregate with no members falls back to its own declared values. Each rule is overridable per type, so a type that wants different behaviour just defines the function. See Errata.Aggregate for the full reasoning.

Members must be Errata errors

Anything else raises ArgumentError when the aggregate is built. That is deliberate: the merge rules are defined in terms of severity/1, retryable?/1, and http_status/1, which a bare map or a foreign exception cannot answer. Wrap a foreign error in an Errata type first — that is what Errata.wrap/3 is for.