Erlang -- Errors and Error Handling

User's Guide
PDF
Top

Erlang Reference Manual
User's Guide
Version 5.9.2

Expand All
Contract All

Chapters

- Introduction
  - Top of chapter
  - Purpose
  - Prerequisites
  - Document Conventions
  - Complete List of BIFs
  - Reserved Words
  - Character Set
- Data Types
  - Top of chapter
  - Terms
  - Number
  - Atom
  - Bit Strings and Binaries
  - Reference
  - Fun
  - Port Identifier
  - Pid
  - Tuple
  - List
  - String
  - Record
  - Boolean
  - Escape Sequences
  - Type Conversions
- Pattern Matching
  - Top of chapter
  - Pattern Matching
- Modules
  - Top of chapter
  - Module Syntax
  - Module Attributes
  - Comments
  - The 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
  - Introduction of Types
  - 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
  - Bit Syntax Expressions
  - Fun Expressions
  - Catch and Throw
  - Try
  - Parenthesized Expressions
  - Block Expressions
  - List Comprehensions
  - Bit String Comprehensions
  - Guard Sequences
  - Operator Precedence
- The 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

# 10 Errors and Error Handling

### 10.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, should 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 could be that nothing happens when a button in a graphical user interface is clicked.

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.

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. Note 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 which 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. Note that a process may terminate/exit for other reasons than a failure.

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

### 10.2 Exceptions

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

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

Table 10.1: Exception Classes.

An exception consists of its class, an exit reason (the Exit Reason), and a stack trace (that 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.

### 10.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 the Expressions chapter about Catch and Try.

#### Error Handling Between Processes

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

### 10.4 Exit Reasons

When a run-time error occurs, that is an exception of class error, the exit reason is a tuple {Reason,Stack}. 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} | There is something 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 10.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 may in some cases be {Module,Name,[Arg]}.