<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2003</year><year>2021</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.
    
    </legalnotice>

    <title>Errors and Error Handling</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
    <file>errors.xml</file>
  </header>

  <section>
    <title>Terminology</title>
    <p>Errors can roughly be divided into four different types:</p>
    <taglist>
      <tag>Compile-time errors</tag>
      <item>When the compiler fails to compile the program, for example a syntax error.</item>
      <tag>Logical errors</tag>
      <item>When a program does not behave as intended, but does not crash.
        An example is that nothing happens when a button in a graphical user
        interface is clicked.</item>
      <tag><marker id="run-time-errors"/>Run-time errors</tag>
      <item>When a crash occurs. An example is
        when an operator is applied to arguments of the wrong type.
        The Erlang programming language has built-in features for
        handling of run-time errors. A run-time error can also be
        emulated by calling <seemfa marker="erts:erlang#error/1">
        <c>error(Reason)</c></seemfa>. Run-time errors are exceptions of
        class <c>error</c>.</item>
      <tag><marker id="generated-errors"/>Generated errors</tag>
      <item>When the code itself calls <seemfa marker="erts:erlang#exit/1">
        <c>exit/1</c></seemfa> or <seemfa marker="erts:erlang#throw/1">
        <c>throw/1</c></seemfa>. Generated errors are exceptions of
        class <c>exit</c> or <c>throw</c>.</item>
    </taglist>
    <p>When an exception occurs in Erlang, execution of the process that
      evaluated the erroneous expression is stopped. This is referred to as a
      <em>failure</em>, that execution or evaluation <em>fails</em>, or that the
      process <em>fails</em>, <em>terminates</em>, or <em>exits</em>. Notice that
      a process can terminate/exit for other reasons than a failure.</p>
    <p>A process that terminates emits an <em>exit signal</em> with
      an <em>exit reason</em> that describes why the process terminated.
      Normally, some information about any erroneous termination is printed
      to the terminal. See <seeguide marker="processes#term">
      Process Termination</seeguide> in the Processes chapter for more details
      on termination.</p>
  </section>

  <section>
    <title>Exceptions</title>
    <p>Exceptions are <seeguide marker="#run-time-errors">run-time errors</seeguide> or
      <seeguide marker="#generated-errors">generated errors</seeguide> and
      are of three different classes, with different origins. The
      <seeguide marker="expressions#try">try</seeguide> expression
      can distinguish between the different classes, whereas the
      <seeguide marker="expressions#catch">catch</seeguide>
      expression cannot. <c>try</c> and <c>catch</c> are described in
      <seeguide marker="expressions">Expressions</seeguide>.</p>
    <table>
      <row>
        <cell align="left" valign="middle"><em>Class</em></cell>
        <cell align="left" valign="middle"><em>Origin</em></cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>error</c></cell>
        <cell align="left" valign="middle">Run-time error,
        for example, <c>1+a</c>, or the process called
        <c>error/1,2</c></cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>exit</c></cell>
        <cell align="left" valign="middle">The process called <c>exit/1</c></cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>throw</c></cell>
        <cell align="left" valign="middle">The process called <c>throw/1</c></cell>
      </row>
      <tcaption>Exception Classes.</tcaption>
    </table>
    <p>All of the above exceptions can also be generated by calling
      <seemfa marker="erts:erlang#raise/3"><c>erlang:raise/3</c></seemfa>.</p>
    <p>An exception consists of its class, an exit reason
      (see <seeguide marker="#exit_reasons">Exit Reason</seeguide>),
      and a stack trace (which aids in finding the code location of
      the exception).</p>
    <p>The stack trace can be bound to a variable from within a <c>try</c>
      expression for any exception class, or as part of the exit reason when
      a run-time error is caught by a <c>catch</c>. Example:</p>
      <pre>
> <input>{'EXIT',{test,Stacktrace}} = (catch error(test)), Stacktrace.</input>
[{shell,apply_fun,3,[]},
 {erl_eval,do_apply,6,[]},
 ...]
> <input>try throw(test) catch Class:Reason:Stacktrace -> Stacktrace end.</input>
[{shell,apply_fun,3,[]},
 {erl_eval,do_apply,6,[]},
 ...]</pre>
      <section>
	<marker id="stacktrace"></marker>
	<title>The call-stack back trace (stacktrace)</title>
        <p>The stack back-trace
          (<seetype marker="erts:erlang#stacktrace"><em>stacktrace</em></seetype>)
          is a list contains <c>{Module, Function, Arity, ExtraInfo}</c>
          and/or <c>{Fun, Arity, ExtraInfo}</c> tuples. The field <c>Arity</c> in the
          tuple can be the argument list of that function call instead of an
          arity integer, depending on the exception.</p>
	  <p><c>ExtraInfo</c> is a (possibly empty) list of two-element tuples
	  in any order that provides additional information about the exception.
	  The first element is an atom describing the type of
	  information in the second element. The following items can
	  occur:</p>
	<taglist>
          <tag><c>error_info</c></tag>
          <item>The second element of the tuple is a map
	  providing additional information about what caused the
	  exception. This information can be created by calling
          <seemfa marker="erts:erlang#error/3"><c>error/3</c></seemfa>
          and is used by
          <seemfa marker="stdlib:erl_error#format_exception/4">
            <c>erl_error:format_exception/4</c></seemfa>.
          </item>
          <tag><c>file</c></tag>
          <item>The second element of the tuple is a string (list of
          characters) representing the filename of the source file
          of the function.
          </item>
          <tag><c>line</c></tag>
          <item>The second element of the tuple is the line number
          (an integer &gt; 0) in the source file
          where the exception occurred or the function was called.
          </item>
	</taglist>
	<warning><p>Developers should rely on stacktrace entries only for
	debugging purposes.</p>
	<p>The VM performs tail call optimization, which
	does not add new entries to the stacktrace, and also limits stacktraces
	to a certain depth. Furthermore, compiler options, optimizations and
	future changes may add or remove stacktrace entries, causing any code
	that expects the stacktrace to be in a certain order or contain specific
	items to fail.</p>
	<p>The only exception to this rule is the class <c>error</c> with the
	reason <c>undef</c> which is guaranteed to include the <c>Module</c>,
	<c>Function</c> and <c>Arity</c> of the attempted
	function as the first stacktrace entry.</p>
	</warning>
      </section>

  </section>


  <section>
    <title>Handling of Run-time Errors in Erlang</title>

    <section>
      <title>Error Handling Within Processes</title>
      <p>It is possible to prevent run-time errors and other
        exceptions from causing the process to terminate by using <c>catch</c> or
        <c>try</c>, see <seeguide marker="expressions">
        Expressions</seeguide> about
        <seeguide marker="expressions#catch">catch</seeguide>
        and <seeguide marker="expressions#try">try</seeguide>.</p>
    </section>

    <section>
      <title>Error Handling Between Processes</title>
      <p>Processes can monitor other processes and detect process
        terminations, see
        <seeguide marker="processes#errors">Processes</seeguide>.</p>
    </section>
  </section>

  <section>
    <marker id="exit_reasons"></marker>
    <title>Exit Reasons</title>
    <p>When a run-time error occurs, that is an exception of class <c>error</c>.
      The exit reason is a tuple <c>{Reason,Stack}</c>, where
      <c>Reason</c> is a term indicating the type of error:</p>
    <table>
      <row>
        <cell align="left" valign="middle"><em>Reason</em></cell>
        <cell align="left" valign="middle"><em>Type of Error</em></cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>badarg</c></cell>
        <cell align="left" valign="middle">Bad argument. The argument is of wrong data type, or is otherwise badly formed.</cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>badarith</c></cell>
        <cell align="left" valign="middle">Bad argument in an arithmetic expression.</cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>{badmatch,V}</c></cell>
        <cell align="left" valign="middle">Evaluation of a match expression failed. The value <c>V</c> did not match.</cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>function_clause</c></cell>
        <cell align="left" valign="middle">No matching function clause is found when evaluating a function call.</cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>{case_clause,V}</c></cell>
        <cell align="left" valign="middle">No matching branch is found when evaluating a <c>case</c> expression. The value <c>V</c> did not match.</cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>if_clause</c></cell>
        <cell align="left" valign="middle">No true branch is found when evaluating an <c>if</c> expression.</cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>{try_clause,V}</c></cell>
        <cell align="left" valign="middle">No matching branch is found when evaluating the of-section of a <c>try</c> expression. The value <c>V</c> did not match.</cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>undef</c></cell>
        <cell align="left" valign="middle">The function cannot be found when evaluating a function call.</cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>{badfun,F}</c></cell>
        <cell align="left" valign="middle">Something is wrong with a fun <c>F</c>.</cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>{badarity,F}</c></cell>
        <cell align="left" valign="middle">A fun is applied to the wrong number of arguments. <c>F</c> describes the fun and the arguments.</cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>timeout_value</c></cell>
        <cell align="left" valign="middle">The timeout value in a <c>receive..after</c> expression is evaluated to something else than an integer or <c>infinity</c>.</cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>noproc</c></cell>
        <cell align="left" valign="middle">Trying to link or monitor to a non-existing process or port.</cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>noconnection</c></cell>
        <cell align="left" valign="middle">A link or monitor to a remote process was broken because a connection between the nodes could not be established or was severed.</cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>{nocatch,V}</c></cell>
        <cell align="left" valign="middle">Trying to evaluate a <c>throw </c>outside a <c>catch</c>. <c>V</c> is the thrown term.</cell>
      </row>
      <row>
        <cell align="left" valign="middle"><c>system_limit</c></cell>
        <cell align="left" valign="middle">A system limit has been reached.
        See <seeguide marker="system/efficiency_guide:advanced">
        Efficiency Guide</seeguide> for information about system limits.
        </cell>
      </row>
      <tcaption>Exit Reasons</tcaption>
    </table>
    <p><c>Stack</c> is the stack of function calls being evaluated
      when the error occurred, given as a list of tuples
      <c>{Module,Name,Arity,ExtraInfo}</c> with the most recent function call
      first. The most recent function call tuple can in some
      cases be <c>{Module,Name,[Arg],ExtraInfo}</c>.</p>
  </section>
</chapter>

