Erlang -- Errors and Error Handling

User's Guide
PDF
Top

Erlang Reference Manual
User's Guide
Version 7.3

Expand All
Contract All

Chapters

- Introduction
  - Top of chapter
  - Purpose
  - Prerequisites
  - Document Conventions
  - Complete List of BIFs
  - Reserved Words
- Character Set and Source File Encoding
  - Top of chapter
  - Character Set
  - Source File Encoding
- Data Types
  - Top of chapter
  - Terms
  - Number
  - Atom
  - Bit Strings and Binaries
  - Reference
  - Fun
  - Port Identifier
  - Pid
  - Tuple
  - Map
  - List
  - String
  - Record
  - Boolean
  - Escape Sequences
  - Type Conversions
- Pattern Matching
  - Top of chapter
  - Pattern Matching
- Modules
  - Top of chapter
  - Module Syntax
  - Module Attributes
  - Comments
  - module_info/0 and module_info/1 functions
- Functions
  - Top of chapter
  - Function Declaration Syntax
  - Function Evaluation
  - Tail recursion
  - Built-In Functions (BIFs)
- Types and Function Specifications
  - Top of chapter
  - The Erlang Type Language
  - Types and their Syntax
  - Type Declarations of User-Defined Types
  - Type Information in Record Declarations
  - Specifications for Functions
- Expressions
  - Top of chapter
  - Expression Evaluation
  - Terms
  - Variables
  - Patterns
  - Match
  - Function Calls
  - If
  - Case
  - Send
  - Receive
  - Term Comparisons
  - Arithmetic Expressions
  - Boolean Expressions
  - Short-Circuit Expressions
  - List Operations
  - Map Expressions
  - Bit Syntax Expressions
  - Fun Expressions
  - Catch and Throw
  - Try
  - Parenthesized Expressions
  - Block Expressions
  - List Comprehensions
  - Bit String Comprehensions
  - Guard Sequences
  - Operator Precedence
- Preprocessor
  - Top of chapter
  - File Inclusion
  - Defining and Using Macros
  - Predefined Macros
  - Macros Overloading
  - Flow Control in Macros
  - Stringifying Macro Arguments
- Records
  - Top of chapter
  - Defining Records
  - Creating Records
  - Accessing Record Fields
  - Updating Records
  - Records in Guards
  - Records in Patterns
  - Nested Records
  - Internal Representation of Records
- Errors and Error Handling
  - Top of chapter
  - Terminology
  - Exceptions
  - Handling of Run-time Errors in Erlang
  - Exit Reasons
- Processes
  - Top of chapter
  - Processes
  - Process Creation
  - Registered Processes
  - Process Termination
  - Message Sending
  - Links
  - Error Handling
  - Monitors
  - Process Dictionary
- Distributed Erlang
  - Top of chapter
  - Distributed Erlang System
  - Nodes
  - Node Connections
  - epmd
  - Hidden Nodes
  - C Nodes
  - Security
  - Distribution BIFs
  - Distribution Command-Line Flags
  - Distribution Modules
- Compilation and Code Loading
  - Top of chapter
  - Compilation
  - Code Loading
  - Code Replacement
  - Running a Function When a Module is Loaded
- Ports and Port Drivers
  - Top of chapter
  - Ports
  - Port Drivers
  - Port BIFs

# 11 Errors and Error Handling

### 11.1 Terminology

Errors can roughly be divided into four different types:

- Compile-time errors
- Logical errors
- Run-time errors
- Generated errors

A compile-time error, for example a syntax error, does not cause much trouble as it is caught by the compiler.

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.

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.

A run-time error can also be emulated by calling erlang:error(Reason) or erlang:error(Reason, Args) (those appeared in Erlang 5.4/OTP-R10).

A run-time error is another name for an exception of class error.

A generated error is when the code itself calls exit/1 or throw/1. Notice that emulated run-time errors are not denoted as generated errors here.

Generated errors are exceptions of classes exit and throw.

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 failure, that execution or evaluation fails, or that the process fails, terminates, or exits. Notice that a process can terminate/exit for other reasons than a failure.

A process that terminates emits an exit signal with an exit reason that says something about which error has occurred. Normally, some information about the error is printed to the terminal.

### 11.2 Exceptions

Exceptions are run-time errors or generated errors and are of three different classes, with different origins. The try expression (new in Erlang 5.4/OTP R10B) can distinguish between the different classes, whereas the catch expression cannot. They are described in Expressions .

Class | Origin
error | Run-time error, for example, 1+a, or the process called erlang:error/1,2 (new in Erlang 5.4/OTP R10B)
exit | The process called exit/1
throw | The process called throw/1

Table 11.1: Exception Classes.

An exception consists of its class, an exit reason (see Exit Reason), and a stack trace (which aids in finding the code location of the exception).

The stack trace can be retrieved using erlang:get_stacktrace/0 (new in Erlang 5.4/OTP R10B) from within a try expression, and is returned for exceptions of class error from a catch expression.

An exception of class error is also known as a run-time error.

### 11.3 Handling of Run-time Errors in Erlang

#### Error Handling Within Processes

It is possible to prevent run-time errors and other exceptions from causing the process to terminate by using catch or try, see Expressions about catch and try.

#### Error Handling Between Processes

Processes can monitor other processes and detect process terminations, see Processes.

### 11.4 Exit Reasons

When a run-time error occurs, that is an exception of class error. The exit reason is a tuple {Reason,Stack}, where Reason is a term indicating the type of error:

Reason | Type of Error
badarg | Bad argument. The argument is of wrong data type, or is otherwise badly formed.
badarith | Bad argument in an arithmetic expression.
{badmatch,V} | Evaluation of a match expression failed. The value V did not match.
function_clause | No matching function clause is found when evaluating a function call.
{case_clause,V} | No matching branch is found when evaluating a case expression. The value V did not match.
if_clause | No true branch is found when evaluating an if expression.
{try_clause,V} | No matching branch is found when evaluating the of-section of a try expression. The value V did not match.
undef | The function cannot be found when evaluating a function call.
{badfun,F} | Something is wrong with a fun F.
{badarity,F} | A fun is applied to the wrong number of arguments. F describes the fun and the arguments.
timeout_value | The timeout value in a receive..after expression is evaluated to something else than an integer or infinity.
noproc | Trying to link to a non-existing process.
{nocatch,V} | Trying to evaluate a throw outside a catch. V is the thrown term.
system_limit | A system limit has been reached. See Efficiency Guide for information about system limits.

Table 11.2: Exit Reasons

Stack is the stack of function calls being evaluated when the error occurred, given as a list of tuples {Module,Name,Arity} with the most recent function call first. The most recent function call tuple can in some cases be {Module,Name,[Arg]}.