<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html xmlns:fn="http://www.w3.org/2005/02/xpath-functions"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <link rel="stylesheet" href="../otp_doc.css" type="text/css"> <title>Erlang -- Errors and Error Handling</title> </head> <body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container"> <script id="js" type="text/javascript" language="JavaScript" src="../js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript"> <!-- function getWinHeight() { var myHeight = 0; if( typeof( window.innerHeight ) == 'number' ) { //Non-IE myHeight = window.innerHeight; } else if( document.documentElement && ( document.documentElement.clientWidth || document.documentElement.clientHeight ) ) { //IE 6+ in 'standards compliant mode' myHeight = document.documentElement.clientHeight; } else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) { //IE 4 compatible myHeight = document.body.clientHeight; } return myHeight; } function setscrollpos() { var objf=document.getElementById('loadscrollpos'); document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2; } function addEvent(obj, evType, fn){ if (obj.addEventListener){ obj.addEventListener(evType, fn, true); return true; } else if (obj.attachEvent){ var r = obj.attachEvent("on"+evType, fn); return r; } else { return false; } } addEvent(window, 'load', setscrollpos); //--></script><div id="leftnav"><div class="innertube"> <img alt="Erlang logo" src="../erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="../pdf/otp-system-documentation-5.7.5.pdf">PDF</a><br><a href="../index.html">Top</a></small><p><strong>Erlang Reference Manual</strong><br><strong>User's Guide</strong><br><small>Version 5.7.5</small></p> <br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p> <ul class="flipMenu" imagepath="../js/flipmenu"> <li id="no" title="Introduction" expanded="false">Introduction<ul> <li><a href="introduction.html"> Top of chapter </a></li> <li title="Purpose"><a href="introduction.html#id2255253">Purpose</a></li> <li title="Prerequisites"><a href="introduction.html#id2252190">Prerequisites</a></li> <li title="Document Conventions"><a href="introduction.html#id2254389">Document Conventions</a></li> <li title="Complete List of BIFs"><a href="introduction.html#id2252818">Complete List of BIFs</a></li> <li title="Reserved Words"><a href="introduction.html#id2260827">Reserved Words</a></li> <li title="Character Set"><a href="introduction.html#id2266064">Character Set</a></li> </ul> </li> <li id="no" title="Data Types" expanded="false">Data Types<ul> <li><a href="data_types.html"> Top of chapter </a></li> <li title="Terms"><a href="data_types.html#id2265309">Terms</a></li> <li title="Number"><a href="data_types.html#id2253001">Number</a></li> <li title="Atom"><a href="data_types.html#id2259848">Atom</a></li> <li title="Bit Strings and Binaries"><a href="data_types.html#id2257844">Bit Strings and Binaries</a></li> <li title="Reference"><a href="data_types.html#id2265338">Reference</a></li> <li title="Fun"><a href="data_types.html#id2265020">Fun</a></li> <li title="Port Identifier"><a href="data_types.html#id2260799">Port Identifier</a></li> <li title="Pid"><a href="data_types.html#id2263912">Pid</a></li> <li title="Tuple"><a href="data_types.html#id2264766">Tuple</a></li> <li title="List"><a href="data_types.html#id2259788">List</a></li> <li title="String"><a href="data_types.html#id2263762">String</a></li> <li title="Record"><a href="data_types.html#id2263803">Record</a></li> <li title="Boolean"><a href="data_types.html#id2252704">Boolean</a></li> <li title="Escape Sequences"><a href="data_types.html#id2252738">Escape Sequences</a></li> <li title="Type Conversions"><a href="data_types.html#id2271721">Type Conversions</a></li> </ul> </li> <li id="no" title="Pattern Matching" expanded="false">Pattern Matching<ul> <li><a href="patterns.html"> Top of chapter </a></li> <li title="Pattern Matching"><a href="patterns.html#id2270180">Pattern Matching</a></li> </ul> </li> <li id="no" title="Modules" expanded="false">Modules<ul> <li><a href="modules.html"> Top of chapter </a></li> <li title="Module Syntax"><a href="modules.html#id2270316">Module Syntax</a></li> <li title="Module Attributes"><a href="modules.html#id2270352">Module Attributes</a></li> <li title="Comments"><a href="modules.html#id2270781">Comments</a></li> <li title="The module_info/0 and module_info/1 functions"><a href="modules.html#id2270797">The module_info/0 and module_info/1 functions</a></li> </ul> </li> <li id="no" title="Functions" expanded="false">Functions<ul> <li><a href="functions.html"> Top of chapter </a></li> <li title="Function Declaration Syntax"><a href="functions.html#id2271076">Function Declaration Syntax</a></li> <li title="Function Evaluation"><a href="functions.html#id2271201">Function Evaluation</a></li> <li title="Tail recursion"><a href="functions.html#id2271366">Tail recursion</a></li> <li title="Built-In Functions, BIFs"><a href="functions.html#id2271403">Built-In Functions, BIFs</a></li> </ul> </li> <li id="no" title="Types and Function Specifications" expanded="false">Types and Function Specifications<ul> <li><a href="typespec.html"> Top of chapter </a></li> <li title="Introduction of Types"><a href="typespec.html#id2271533">Introduction of Types</a></li> <li title="Types and their Syntax"><a href="typespec.html#id2271594">Types and their Syntax</a></li> <li title="Type declarations of user-defined types"><a href="typespec.html#id2272398">Type declarations of user-defined types</a></li> <li title=" Type information in record declarations "><a href="typespec.html#id2272454"> Type information in record declarations </a></li> <li title="Specifications (contracts) for functions"><a href="typespec.html#id2272544">Specifications (contracts) for functions</a></li> </ul> </li> <li id="no" title="Expressions" expanded="false">Expressions<ul> <li><a href="expressions.html"> Top of chapter </a></li> <li title="Expression Evaluation"><a href="expressions.html#id2272779">Expression Evaluation</a></li> <li title="Terms"><a href="expressions.html#id2272826">Terms</a></li> <li title="Variables"><a href="expressions.html#id2272840">Variables</a></li> <li title="Patterns"><a href="expressions.html#id2272985">Patterns</a></li> <li title="Match"><a href="expressions.html#id2273115">Match</a></li> <li title="Function Calls"><a href="expressions.html#id2273176">Function Calls</a></li> <li title="If"><a href="expressions.html#id2273319">If</a></li> <li title="Case"><a href="expressions.html#id2273390">Case</a></li> <li title="Send"><a href="expressions.html#id2273460">Send</a></li> <li title="Receive"><a href="expressions.html#id2273548">Receive</a></li> <li title="Term Comparisons"><a href="expressions.html#id2273735">Term Comparisons</a></li> <li title="Arithmetic Expressions"><a href="expressions.html#id2274000">Arithmetic Expressions</a></li> <li title="Boolean Expressions"><a href="expressions.html#id2274511">Boolean Expressions</a></li> <li title="Short-Circuit Expressions"><a href="expressions.html#id2274668">Short-Circuit Expressions</a></li> <li title="List Operations"><a href="expressions.html#id2274790">List Operations</a></li> <li title="Bit Syntax Expressions"><a href="expressions.html#id2274864">Bit Syntax Expressions</a></li> <li title="Fun Expressions"><a href="expressions.html#id2275447">Fun Expressions</a></li> <li title="Catch and Throw"><a href="expressions.html#id2275626">Catch and Throw</a></li> <li title="Try"><a href="expressions.html#id2275780">Try</a></li> <li title="Parenthesized Expressions"><a href="expressions.html#id2276172">Parenthesized Expressions</a></li> <li title="Block Expressions"><a href="expressions.html#id2276207">Block Expressions</a></li> <li title="List Comprehensions"><a href="expressions.html#id2276233">List Comprehensions</a></li> <li title="Bit String Comprehensions"><a href="expressions.html#id2276384">Bit String Comprehensions</a></li> <li title="Guard Sequences"><a href="expressions.html#id2276526">Guard Sequences</a></li> <li title="Operator Precedence"><a href="expressions.html#id2277066">Operator Precedence</a></li> </ul> </li> <li id="no" title="The Preprocessor" expanded="false">The Preprocessor<ul> <li><a href="macros.html"> Top of chapter </a></li> <li title="File Inclusion"><a href="macros.html#id2277395">File Inclusion</a></li> <li title="Defining and Using Macros"><a href="macros.html#id2277538">Defining and Using Macros</a></li> <li title="Predefined Macros"><a href="macros.html#id2277673">Predefined Macros</a></li> <li title="Macros Overloading"><a href="macros.html#id2277743">Macros Overloading</a></li> <li title="Flow Control in Macros"><a href="macros.html#id2277818">Flow Control in Macros</a></li> <li title="Stringifying Macro Arguments"><a href="macros.html#id2277962">Stringifying Macro Arguments</a></li> </ul> </li> <li id="no" title="Records" expanded="false">Records<ul> <li><a href="records.html"> Top of chapter </a></li> <li title="Defining Records"><a href="records.html#id2278098">Defining Records</a></li> <li title="Creating Records"><a href="records.html#id2278135">Creating Records</a></li> <li title="Accessing Record Fields"><a href="records.html#id2278197">Accessing Record Fields</a></li> <li title="Updating Records"><a href="records.html#id2278240">Updating Records</a></li> <li title="Records in Guards"><a href="records.html#id2278275">Records in Guards</a></li> <li title="Records in Patterns"><a href="records.html#id2278311">Records in Patterns</a></li> <li title="Internal Representation of Records"><a href="records.html#id2278340">Internal Representation of Records</a></li> </ul> </li> <li id="loadscrollpos" title="Errors and Error Handling" expanded="true">Errors and Error Handling<ul> <li><a href="errors.html"> Top of chapter </a></li> <li title="Terminology"><a href="errors.html#id2278472">Terminology</a></li> <li title="Exceptions"><a href="errors.html#id2278622">Exceptions</a></li> <li title="Handling of Run-Time Errors in Erlang"><a href="errors.html#id2278806">Handling of Run-Time Errors in Erlang</a></li> <li title="Exit Reasons"><a href="errors.html#id2278873">Exit Reasons</a></li> </ul> </li> <li id="no" title="Processes" expanded="false">Processes<ul> <li><a href="processes.html"> Top of chapter </a></li> <li title="Processes"><a href="processes.html#id2279365">Processes</a></li> <li title="Process Creation"><a href="processes.html#id2279380">Process Creation</a></li> <li title="Registered Processes"><a href="processes.html#id2279433">Registered Processes</a></li> <li title="Process Termination"><a href="processes.html#id2279548">Process Termination</a></li> <li title="Message Sending"><a href="processes.html#id2279644">Message Sending</a></li> <li title="Links"><a href="processes.html#id2279676">Links</a></li> <li title="Error Handling"><a href="processes.html#id2279746">Error Handling</a></li> <li title="Monitors"><a href="processes.html#id2279871">Monitors</a></li> <li title="Process Dictionary"><a href="processes.html#id2279969">Process Dictionary</a></li> </ul> </li> <li id="no" title="Distributed Erlang" expanded="false">Distributed Erlang<ul> <li><a href="distributed.html"> Top of chapter </a></li> <li title="Distributed Erlang System"><a href="distributed.html#id2280043">Distributed Erlang System</a></li> <li title="Nodes"><a href="distributed.html#id2280079">Nodes</a></li> <li title="Node Connections"><a href="distributed.html#id2280154">Node Connections</a></li> <li title="epmd"><a href="distributed.html#id2280210">epmd</a></li> <li title="Hidden Nodes"><a href="distributed.html#id2280232">Hidden Nodes</a></li> <li title="C Nodes"><a href="distributed.html#id2280285">C Nodes</a></li> <li title="Security"><a href="distributed.html#id2280311">Security</a></li> <li title="Distribution BIFs"><a href="distributed.html#id2280439">Distribution BIFs</a></li> <li title="Distribution Command Line Flags"><a href="distributed.html#id2280745">Distribution Command Line Flags</a></li> <li title="Distribution Modules"><a href="distributed.html#id2280886">Distribution Modules</a></li> </ul> </li> <li id="no" title="Compilation and Code Loading" expanded="false">Compilation and Code Loading<ul> <li><a href="code_loading.html"> Top of chapter </a></li> <li title="Compilation"><a href="code_loading.html#id2281100">Compilation</a></li> <li title="Code Loading"><a href="code_loading.html#id2281218">Code Loading</a></li> <li title="Code Replacement"><a href="code_loading.html#id2281268">Code Replacement</a></li> <li title="Running a function when a module is loaded"><a href="code_loading.html#id2281355">Running a function when a module is loaded</a></li> </ul> </li> <li id="no" title="Ports and Port Drivers" expanded="false">Ports and Port Drivers<ul> <li><a href="ports.html"> Top of chapter </a></li> <li title="Ports"><a href="ports.html#id2281515">Ports</a></li> <li title="Port Drivers"><a href="ports.html#id2281557">Port Drivers</a></li> <li title="Port BIFs"><a href="ports.html#id2281600">Port BIFs</a></li> </ul> </li> </ul> </div></div> <div id="content"> <div class="innertube"> <h1>10 Errors and Error Handling</h1> <h3><a name="id2278472">10.1 Terminology</a></h3> <p>Errors can roughly be divided into four different types:</p> <ul> <li>Compile-time errors</li> <li>Logical errors</li> <li>Run-time errors</li> <li>Generated errors</li> </ul> <p>A compile-time error, for example a syntax error, should 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 could be 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 could be 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 <span class="code">erlang:error(Reason)</span>, <span class="code">erlang:error(Reason, Args)</span> (those appeared in Erlang 5.4/OTP-R10), <span class="code">erlang:fault(Reason)</span> or <span class="code">erlang:fault(Reason, Args)</span> (old equivalents).</p> <p>A run-time error is another name for an exception of class <span class="code">error</span>. </p> <p>A generated error is when the code itself calls <span class="code">exit/1</span> or <span class="code">throw/1</span>. Note that emulated run-time errors are not denoted as generated errors here. </p> <p>Generated errors are exceptions of classes <span class="code">exit</span> and <span class="code">throw</span>. </p> <p>When a run-time error or generated error occurs in Erlang, execution for the process which evaluated the erroneous expression is stopped. This is referred to as a <strong>failure</strong>, that execution or evaluation <strong>fails</strong>, or that the process <strong>fails</strong>, <strong>terminates</strong> or <strong>exits</strong>. Note that a process may terminate/exit for other reasons than a failure.</p> <p>A process that terminates will emit an <strong>exit signal</strong> with an <strong>exit reason</strong> that says something about which error has occurred. Normally, some information about the error will be printed to the terminal.</p> <h3><a name="id2278622">10.2 Exceptions</a></h3> <p>Exceptions are run-time errors or generated errors and are of three different classes, with different origins. The <span class="bold_code"><a href="expressions.html#try">try</a></span> expression (appeared in Erlang 5.4/OTP-R10B) can distinguish between the different classes, whereas the <span class="bold_code"><a href="expressions.html#catch">catch</a></span> expression can not. They are described in the Expressions chapter.</p> <table border="1" cellpadding="2" cellspacing="0"> <tr> <td align="left" valign="middle"><strong>Class</strong></td> <td align="left" valign="middle"><strong>Origin</strong></td> </tr> <tr> <td align="left" valign="middle"><span class="code">error</span></td> <td align="left" valign="middle">Run-time error for example <span class="code">1+a</span>, or the process called <span class="code">erlang:error/1,2</span> (appeared in Erlang 5.4/OTP-R10B) or <span class="code">erlang:fault/1,2</span> (old equivalent)</td> </tr> <tr> <td align="left" valign="middle"><span class="code">exit</span></td> <td align="left" valign="middle">The process called <span class="code">exit/1</span> </td> </tr> <tr> <td align="left" valign="middle"><span class="code">throw</span></td> <td align="left" valign="middle">The process called <span class="code">throw/1</span> </td> </tr> </table> <em>Table 10.1: Exception Classes.</em> <p>An exception consists of its class, an exit reason (the <span class="bold_code"><a href="#exit_reasons">Exit Reason</a></span>), and a stack trace (that aids in finding the code location of the exception).</p> <p>The stack trace can be retrieved using <span class="code">erlang:get_stacktrace/0</span> (new in Erlang 5.4/OTP-R10B from within a <span class="code">try</span> expression, and is returned for exceptions of class <span class="code">error</span> from a <span class="code">catch</span> expression.</p> <p>An exception of class <span class="code">error</span> is also known as a run-time error.</p> <h3><a name="id2278806">10.3 Handling of Run-Time Errors in Erlang</a></h3> <h4>Error Handling Within Processes</h4> <p>It is possible to prevent run-time errors and other exceptions from causing the process to terminate by using <span class="code">catch</span> or <span class="code">try</span>, see the Expressions chapter about <span class="bold_code"><a href="expressions.html#catch">Catch</a></span> and <span class="bold_code"><a href="expressions.html#try">Try</a></span>.</p> <h4>Error Handling Between Processes</h4> <p>Processes can monitor other processes and detect process terminations, see the <span class="bold_code"><a href="processes.html#errors">Processes</a></span> chapter.</p> <h3><a name="id2278873">10.4 Exit Reasons</a></h3> <a name="exit_reasons"></a> <p>When a run-time error occurs, that is an exception of class <span class="code">error</span>, the exit reason is a tuple <span class="code">{Reason,Stack}</span>. <span class="code">Reason</span> is a term indicating the type of error:</p> <table border="1" cellpadding="2" cellspacing="0"> <tr> <td align="left" valign="middle"><strong>Reason</strong></td> <td align="left" valign="middle"><strong>Type of error</strong></td> </tr> <tr> <td align="left" valign="middle"><span class="code">badarg</span></td> <td align="left" valign="middle">Bad argument. The argument is of wrong data type, or is otherwise badly formed.</td> </tr> <tr> <td align="left" valign="middle"><span class="code">badarith</span></td> <td align="left" valign="middle">Bad argument in an arithmetic expression.</td> </tr> <tr> <td align="left" valign="middle"><span class="code">{badmatch,V}</span></td> <td align="left" valign="middle">Evaluation of a match expression failed. The value <span class="code">V</span> did not match.</td> </tr> <tr> <td align="left" valign="middle"><span class="code">function_clause</span></td> <td align="left" valign="middle">No matching function clause is found when evaluating a function call.</td> </tr> <tr> <td align="left" valign="middle"><span class="code">{case_clause,V}</span></td> <td align="left" valign="middle">No matching branch is found when evaluating a <span class="code">case</span> expression. The value <span class="code">V</span> did not match.</td> </tr> <tr> <td align="left" valign="middle"><span class="code">if_clause</span></td> <td align="left" valign="middle">No true branch is found when evaluating an <span class="code">if</span> expression.</td> </tr> <tr> <td align="left" valign="middle"><span class="code">{try_clause,V}</span></td> <td align="left" valign="middle">No matching branch is found when evaluating the of-section of a <span class="code">try</span> expression. The value <span class="code">V</span> did not match.</td> </tr> <tr> <td align="left" valign="middle"><span class="code">undef</span></td> <td align="left" valign="middle">The function cannot be found when evaluating a function call.</td> </tr> <tr> <td align="left" valign="middle"><span class="code">{badfun,F}</span></td> <td align="left" valign="middle">There is something wrong with a fun <span class="code">F</span>.</td> </tr> <tr> <td align="left" valign="middle"><span class="code">{badarity,F}</span></td> <td align="left" valign="middle">A fun is applied to the wrong number of arguments. <span class="code">F</span> describes the fun and the arguments.</td> </tr> <tr> <td align="left" valign="middle"><span class="code">timeout_value</span></td> <td align="left" valign="middle">The timeout value in a <span class="code">receive..after</span> expression is evaluated to something else than an integer or <span class="code">infinity</span>.</td> </tr> <tr> <td align="left" valign="middle"><span class="code">noproc</span></td> <td align="left" valign="middle">Trying to link to a non-existing process.</td> </tr> <tr> <td align="left" valign="middle"><span class="code">{nocatch,V}</span></td> <td align="left" valign="middle">Trying to evaluate a <span class="code">throw </span>outside a <span class="code">catch</span>. <span class="code">V</span> is the thrown term.</td> </tr> <tr> <td align="left" valign="middle"><span class="code">system_limit</span></td> <td align="left" valign="middle">A system limit has been reached. See Efficiency Guide for information about system limits.</td> </tr> </table> <em>Table 10.2: Exit Reasons.</em> <p><span class="code">Stack</span> is the stack of function calls being evaluated when the error occurred, given as a list of tuples <span class="code">{Module,Name,Arity}</span> with the most recent function call first. The most recent function call tuple may in some cases be <span class="code">{Module,Name,[Arg]}</span>.</p> </div> <div class="footer"> <hr> <p>Copyright © 2003-2010 Ericsson AB. All Rights Reserved.</p> </div> </div> </div></body> </html>