gleam/docs/runtime-errors.md

Runtime errors

There are several runtime errors that Gleam code can throw. This documentation lists them and their runtime properties.

On Erlang runtime errors are Erlang maps thrown with erlang:error/1, having at least these properties:

Key	Type	Value
gleam_error	Atom	See individual errors
message	String	See individual errors
file	String	A path to the original source file location
module	String	The module the error occurred in
function	String	The function the error occurred in
line	Int	The line number the error occurred on

On JavaScript runtime errors are instances of the JavaScript Error class, having at least these properties added to them:

Key	Type	Value
gleam_error	String	See individual errors
message	String	See individual errors
module	String	The module the error occurred in
function	String	The function the error occurred in
line	Number	The line number the error occurred on

Todo

A panic that indicates that the code has not yet been completed, intended for use in development.

todo
todo as "some message"

Key	Erlang Value	JavaScript Value
gleam_error	todo	"todo"
message	The given message	The given message

Panic

An explicit panic to unconditionally error.

panic
panic as "some message"

Key	Erlang Value	JavaScript Value
gleam_error	panic	"panic"
message	The given message	The given message

Let assert

An inexhaustive pattern match, erroring if the pattern does not match.

let assert Ok(x) = something()
let assert Error(e) = something() as "This should fail"

Key	Erlang Value	JavaScript Value
gleam_error	let_assert	"let_assert"
message	The given message	The given message
value	The unmatched value	The unmatched value
start	The byte-index of the start of the let assert statement	The byte-index of the start of the let assert statement
end	The byte-index of the end of the let assert statement	The byte-index of the end of the let assert statement
pattern_start	The byte-index of the start of the asserted pattern	The byte-index of the start of the asserted pattern
pattern_end	The byte-index of the end of the asserted pattern	The byte-index of the end of the asserted pattern

Assert

An assertion of a boolean value.

The error format of assert differs based on the expression that is asserted. It always has these fields:

Key	Erlang Value	JavaScript Value
gleam_error	assert	"assert"
message	The given message	The given message
kind	The kind of asserted expression	The kind of asserted expression
start	The byte-index of the start of the assert statement	The byte-index of the start of the assert statement
end	The byte-index of the end of the assert expression	The byte-index of the end of the assert expression
expression_start	The byte-index of the start of the asserted expression	The byte-index of the start of the asserted expression

But, depending on the expression that was asserted, it contains additional information which can be used to diagnose the error.

Binary operators

assert level >= 30

Key	Erlang Type	JavaScript Type	Value
kind	Atom	String	binary_operator
operator	Atom	String	The binary operator that was used
left	Map	Object	The left hand side of the operator
right	Map	Object	The left hand side of the operator

Function calls

assert check_some_property(a, b, c)

Key	Erlang Type	JavaScript Type	Value
kind	Atom	String	function_call
arguments	List of map	Array of objects	The arguments of the asserted function

Other expressions

assert other_expression

Key	Erlang Type	JavaScript Type	Value
kind	Atom	String	expression
expression	Map	Object	The value of the asserted expression

The expression maps have this structure:

Key	Erlang Type	JavaScript Type	Value
value	any	any	the value the expression evaluated to at runtime
kind	Atom	String	literal or expression or unevaluated
start	Int	Number	The byte-index of the start of this expression in the source code
end	Int	Number	The byte-index of the end of this expression in the source code

If the expression is a literal, such as True or 15, it will have the literal kind. This signals that its value is not runtime dependent, and may not need to be printed.

If the expression is on the right hand side of a short-circuiting operator, like || or &&, it might not be evaluated. If the operator short-circuits, the right hand side expression will have kind unevaluated.