Exception — Elixir v1.16.3

Search documentation of Elixir

# View Source Exception behaviour (Elixir v1.16.3)

Functions to format throw/catch/exit and exceptions.

Note that stacktraces in Elixir are only available inside catch and rescue by using the `__STACKTRACE__/0` variable.

Do not rely on the particular format returned by the `format*` functions in this module. They may be changed in future releases in order to better suit Elixir's tool chain. In other words, by using the functions in this module it is guaranteed you will format exceptions as in the current Elixir version being used.

# Summary

## Types

arity_or_args()
kind()

The kind handled by formatting functions

location()
non_error_kind()
stacktrace()
stacktrace_entry()
t()

The exception type

## Callbacks

blame(t, stacktrace)

Called from `Exception.blame/3` to augment the exception struct.

exception(term)

Receives the arguments given to `raise/2` and returns the exception struct.

message(t)

Receives the exception struct and must return its message.

## Functions

blame(kind, error, stacktrace)

Attaches information to exceptions for extra debugging.

blame_mfa(module, function, args)

Blames the invocation of the given module, function and arguments.

format(kind, payload, stacktrace \\ [])

Normalizes and formats throw/errors/exits and stacktraces.

format_banner(kind, exception, stacktrace \\ [])

Normalizes and formats any throw/error/exit.

format_exit(reason)

Formats an exit. It returns a string.

format_fa(fun, arity)

Receives an anonymous function and arity and formats it as shown in stacktraces. The arity may also be a list of arguments.

format_file_line(file, line, suffix \\ "")

Formats the given `file` and `line` as shown in stacktraces.

format_file_line_column(file, line, column, suffix \\ "")

Formats the given `file`, `line`, and `column` as shown in stacktraces.

format_mfa(module, fun, arity)

Receives a module, fun and arity and formats it as shown in stacktraces. The arity may also be a list of arguments.

format_stacktrace(trace \\ nil)

Formats the stacktrace.

format_stacktrace_entry(entry)

Receives a stacktrace entry and formats it into a string.

message(exception)

Gets the message for an `exception`.

normalize(kind, payload, stacktrace \\ [])

Normalizes an exception, converting Erlang exceptions to Elixir exceptions.

# Types

Link to this type

# arity_or_args()

View Source

    @type arity_or_args() :: non_neg_integer() | list()

Link to this type

# kind()

View Source

    @type kind() :: :error | non_error_kind()

The kind handled by formatting functions

Link to this type

# location()

View Source

    @type location() :: keyword()

Link to this type

# non_error_kind()

View Source

    @type non_error_kind() :: :exit | :throw | {:EXIT, pid()}

Link to this type

# stacktrace()

View Source

    @type stacktrace() :: [stacktrace_entry()]

Link to this type

# stacktrace_entry()

View Source

    @type stacktrace_entry() ::
      {module(), atom(), arity_or_args(), location()}
      | {(... -> any()), arity_or_args(), location()}

Link to this type

# t()

View Source

    @type t() :: %{
      :__struct__ => module(),
      :__exception__ => true,
      optional(atom()) => any()
    }

The exception type

# Callbacks

Link to this callback

# blame(t, stacktrace)

View Source (optional)

    @callback blame(t(), stacktrace()) :: {t(), stacktrace()}

Called from `Exception.blame/3` to augment the exception struct.

Can be used to collect additional information about the exception or do some additional expensive computation.

Link to this callback

# exception(term)

View Source

    @callback exception(term()) :: t()

Receives the arguments given to `raise/2` and returns the exception struct.

The default implementation accepts either a set of keyword arguments that is merged into the struct or a string to be used as the exception's message.

Link to this callback

# message(t)

View Source

    @callback message(t()) :: String.t()

Receives the exception struct and must return its message.

Most commonly exceptions have a message field which by default is accessed by this function. However, if an exception does not have a message field, this function must be explicitly implemented.

# Functions

Link to this function

# blame(kind, error, stacktrace)

View Source (since 1.5.0)

    @spec blame(:error, any(), stacktrace()) :: {t(), stacktrace()}

    @spec blame(non_error_kind(), payload, stacktrace()) :: {payload, stacktrace()}
    when payload: var

Attaches information to exceptions for extra debugging.

This operation is potentially expensive, as it reads data from the file system, parses beam files, evaluates code and so on.

If the exception module implements the optional `blame/2` callback, it will be invoked to perform the computation.

Link to this function

# blame_mfa(module, function, args)

View Source (since 1.5.0)

    @spec blame_mfa(module(), function :: atom(), args :: [term()]) ::
      {:ok, :def | :defp | :defmacro | :defmacrop,
       [{args :: [term()], guards :: [term()]}]}
      | :error

Blames the invocation of the given module, function and arguments.

This function will retrieve the available clauses from bytecode and evaluate them against the given arguments. The clauses are returned as a list of `{args, guards}` pairs where each argument and each top-level condition in a guard separated by `and`/`or` is wrapped in a tuple with blame metadata.

This function returns either `{:ok, definition, clauses}` or `:error`. Where `definition` is `:def`, `:defp`, `:defmacro` or `:defmacrop`.

Link to this function

# format(kind, payload, stacktrace \\ [])

View Source

    @spec format(kind(), any(), stacktrace()) :: String.t()

Normalizes and formats throw/errors/exits and stacktraces.

It relies on `format_banner/3` and `format_stacktrace/1` to generate the final format.

If `kind` is `{:EXIT, pid}`, it does not generate a stacktrace, as such exits are retrieved as messages without stacktraces.

Link to this function

# format_banner(kind, exception, stacktrace \\ [])

View Source

    @spec format_banner(kind(), any(), stacktrace()) :: String.t()

Normalizes and formats any throw/error/exit.

The message is formatted and displayed in the same format as used by Elixir's CLI.

The third argument is the stacktrace which is used to enrich a normalized error with more information. It is only used when the kind is an error.

Link to this function

# format_exit(reason)

View Source

    @spec format_exit(any()) :: String.t()

Formats an exit. It returns a string.

Often there are errors/exceptions inside exits. Exits are often wrapped by the caller and provide stacktraces too. This function formats exits in a way to nicely show the exit reason, caller and stacktrace.

Link to this function

# format_fa(fun, arity)

View Source

    @spec format_fa((... -> any()), arity()) :: String.t()

Receives an anonymous function and arity and formats it as shown in stacktraces. The arity may also be a list of arguments.

## Examples

    Exception.format_fa(fn -> nil end, 1)
    #=> "#Function<...>/1"

Link to this function

# format_file_line(file, line, suffix \\ "")

View Source

    @spec format_file_line(String.t() | nil, non_neg_integer() | nil, String.t()) ::
      String.t()

Formats the given `file` and `line` as shown in stacktraces.

If any of the values are `nil`, they are omitted.

## Examples

    iex> Exception.format_file_line("foo", 1)
    "foo:1:"

    iex> Exception.format_file_line("foo", nil)
    "foo:"

    iex> Exception.format_file_line(nil, nil)
    ""

Link to this function

# format_file_line_column(file, line, column, suffix \\ "")

View Source

    @spec format_file_line_column(
      String.t() | nil,
      non_neg_integer() | nil,
      non_neg_integer() | nil,
      String.t()
    ) :: String.t()

Formats the given `file`, `line`, and `column` as shown in stacktraces.

If any of the values are `nil`, they are omitted.

## Examples

    iex> Exception.format_file_line_column("foo", 1, 2)
    "foo:1:2:"

    iex> Exception.format_file_line_column("foo", 1, nil)
    "foo:1:"

    iex> Exception.format_file_line_column("foo", nil, nil)
    "foo:"

    iex> Exception.format_file_line_column("foo", nil, 2)
    "foo:"

    iex> Exception.format_file_line_column(nil, nil, nil)
    ""

Link to this function

# format_mfa(module, fun, arity)

View Source

    @spec format_mfa(module(), atom(), arity_or_args()) :: String.t()

Receives a module, fun and arity and formats it as shown in stacktraces. The arity may also be a list of arguments.

## Examples

    iex> Exception.format_mfa(Foo, :bar, 1)
    "Foo.bar/1"

    iex> Exception.format_mfa(Foo, :bar, [])
    "Foo.bar()"

    iex> Exception.format_mfa(nil, :bar, [])
    "nil.bar()"

Anonymous functions are reported as -func/arity-anonfn-count-, where func is the name of the enclosing function. Convert to "anonymous fn in func/arity"

Link to this function

# format_stacktrace(trace \\ nil)

View Source

    @spec format_stacktrace(stacktrace() | nil) :: String.t()

Formats the stacktrace.

A stacktrace must be given as an argument. If not, the stacktrace is retrieved from `Process.info/2`.

Link to this function

# format_stacktrace_entry(entry)

View Source

    @spec format_stacktrace_entry(stacktrace_entry()) :: String.t()

Receives a stacktrace entry and formats it into a string.

Link to this function

# message(exception)

View Source

    @spec message(t()) :: String.t()

Gets the message for an `exception`.

Link to this function

# normalize(kind, payload, stacktrace \\ [])

View Source

    @spec normalize(:error, any(), stacktrace()) :: t()

    @spec normalize(non_error_kind(), payload, stacktrace()) :: payload when payload: var

Normalizes an exception, converting Erlang exceptions to Elixir exceptions.

It takes the `kind` spilled by `catch` as an argument and normalizes only `:error`, returning the untouched payload for others.

The third argument is the stacktrace which is used to enrich a normalized error with more information. It is only used when the kind is an error.