---
name: "erl_error"
section: "3erl"
platform: "linux"
package: "erlang-manpages"
version: "1:25.2.3+dfsg-1+deb12u4"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/erl_error"
---

# erl\_error(3erl)

Utilities for reporting errors.

## NAME

erl\_error - Utilities for reporting errors.

## DESCRIPTION

This module provides functions for pretty-printing errors and exceptions. It is used by both the *shell* and by *proc\_lib* to print exceptions.

It is possible for the module raising an error to provide additional information by calling *error/3* with extra error information. More details about this mechanism is described in EEP-54.

## DATA TYPES

```
format_options() =
    #{column => column(),
      stack_trim_fun => stack_trim_fun(),
      format_fun => format_fun()}
```

A map with formatting options.

```
stack_trim_fun() =
    fun((module(), atom(), arity()) -> boolean())
```

A fun used to trim the end of the stacktrace. It is called with module, function, and arity from an entry from the stacktrace. The fun is to return *true* if the entry should be trimmed, and *false* otherwise. The default value is:

```
fun(_, _, _) -> false end
```

```
format_fun() = fun((term(), column()) -> iolist())
```

A fun used to format function arguments for BIF and function calls. By default the following fun will be used:

```
fun(Term, I) -> io_lib:print(Term, I, 80, 30) end
```

```
column() = integer() >= 1
```

Start column number. Default is 1.

## EXPORTS

```
format_exception(Class, Reason, StackTrace) -> unicode:chardata()
```

```
format_exception(Class, Reason, StackTrace, Options) ->
                    unicode:chardata()
```

Types:

Class = error \| exit \| throw\
 Reason = term()\
 StackTrace = erlang:stacktrace()\
 Options = format\_options()\

Format the error reason and stack back-trace caught using *try* ... *catch* in the same style as the shell formats them.

Example:

```
try
    do_something()
catch
    C:R:Stk ->
        Message = erl_error:format_exception(C, R, Stk),
        io:format(LogFile, "~ts\n", [Message])
end
```

If *error\_info* is provided with the exception, *format\_exception* will use that information to provide additional information about the exception.

Example:

```
try
  erlang:raise(badarg,[],[{error_info,#{}}])
catch
    C:R:Stk ->
        Message = erl_error:format_exception(C, R, Stk),
        io:format(LogFile, "~ts\n", [Message])
end
```

See *erlang:error/3* for details on how to raise an exception with *error\_info* included.

## CALLBACK FUNCTIONS

The following functions are to be exported from an Error Info handler.

## EXPORTS

**Module:format\_error(Reason, StackTrace) -\> ErrorDescription**\

Types:

Reason = term()\
 StackTrace = erlang:stacktrace()\
 ArgumentPosition = pos\_integer()\
 ErrorDescription = \
\
  \#{ ArgumentPosition =\> unicode:chardata(), \
\
  general =\> unicode:chardata(),\
\
  reason =\> unicode:chardata() }\

This callback is called when  *format\_exception/4* or similar functionality wants to provide extra information about an error. The *Module*:*Function* called is the one specificed by the *error\_info* map.

The function should return a map with additional information about what have caused the exception. The possible keys of the map are:

- ***ArgumentPosition = pos\_integer()*:**

  The position of the argument that caused the error starting at 1.

- ***general*:**

  An error that is not associated with any argument caused the error.

- ***reason*:**

  If the *Reason* should be printed differently than the default way.

If the text returned includes new-lines, *format\_exception/4* will indent the text correctly.

Example:

```
-module(my_error_module).
-export([atom_to_string/1, format_error/2]).
atom_to_string(Arg) when is_atom(Arg) ->
  atom_to_list(Arg);
atom_to_string(Arg) ->
  erlang:error(badarg,[Arg],
               [{error_info,#{ module => ?MODULE,
                               cause => #{ 1 => "should be an atom" }}}]).
format_error(Reason, [{_M,_F,_As,Info}|_]) ->
  ErrorInfo = proplists:get_value(error_info, Info, #{}),
  ErrorMap = maps:get(cause, ErrorInfo),
  ErrorMap#{ general => "optional general information",
             reason => io_lib:format("~p: ~p",[?MODULE, Reason]) }.
```

```
1> c(my_error_module).
{ok,my_error_module}
2> my_error_module:atom_to_string(1).
** exception error: my_error_module: badarg
     in function  my_error_module:atom_to_string/1
        called as my_error_module:atom_to_string(1)
        *** argument 1: should be an atom
        *** optional general information
```