<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
<year>2003</year><year>2017</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>
<list type="bulleted">
<item>Compile-time errors</item>
<item>Logical errors</item>
<item>Run-time errors</item>
<item>Generated errors</item>
</list>
<p>A compile-time error, for example a syntax error, does not
cause much trouble as it is caught by the compiler.</p>
<p>A logical error is 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.</p>
<p>A run-time error is 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.</p>
<p>A run-time error can also be emulated by calling
<c>erlang:error(Reason)</c> or <c>erlang:error(Reason, Args)</c>.</p>
<p>A run-time error is another name for an exception
of class <c>error</c>.
</p>
<p>A generated error is when the code itself calls
<c>exit/1</c> or <c>throw/1</c>. Notice that emulated run-time
errors are not denoted as generated errors here.
</p>
<p>Generated errors are exceptions of classes <c>exit</c> and
<c>throw</c>.
</p>
<p>When a run-time error or generated error occurs in Erlang,
execution for 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 says something about which error
has occurred. Normally, some information about the error is
printed to the terminal.</p>
</section>
<section>
<title>Exceptions</title>
<p>Exceptions are run-time errors or generated errors and
are of three different classes, with different origins. The
<seealso marker="expressions#try">try</seealso> expression
can distinguish between the different classes, whereas the
<seealso marker="expressions#catch">catch</seealso>
expression cannot. They are described in
<seealso marker="expressions">Expressions
</seealso>.</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>erlang: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>An exception consists of its class, an exit reason
(see <seealso marker="#exit_reasons">Exit Reason</seealso>),
and a stack trace (which aids in finding the code location of
the exception).</p>
<p>The stack trace can be be bound to a variable from within
a <c>try</c> expression, and is returned for
exceptions of class <c>error</c> from a <c>catch</c> expression.</p>
<p>An exception of class <c>error</c> is also known as a run-time
error.</p>
<section>
<title>The call-stack back trace (stacktrace)</title>
<p>The stack back-trace (<em>stacktrace</em>) is a list of
<c>{Module,Function,Arity,Location}</c>
tuples. The field <c>Arity</c> in the first tuple can be the
argument list of that function call instead of an arity integer,
depending on the exception.</p>
<p><c>Location</c> is a (possibly empty) list of two-tuples
that can indicate the location in the source code of the
function. The first element is an atom describing the type of
information in the second element. The following items can
occur:</p>
<taglist>
<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 > 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 <seealso marker="expressions">
Expressions</seealso> about
<seealso marker="expressions#catch">catch</seealso>
and <seealso marker="expressions#try">try</seealso>.</p>
</section>
<section>
<title>Error Handling Between Processes</title>
<p>Processes can monitor other processes and detect process
terminations, see
<seealso marker="processes#errors">Processes</seealso>.</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 to a non-existing process.</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 <seealso marker="doc/efficiency_guide:advanced">
Efficiency Guide</seealso> 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}</c> with the most recent function call
first. The most recent function call tuple can in some
cases be <c>{Module,Name,[Arg]}</c>.</p>
</section>
</chapter>
