Skip to content

Errors

Option<A> is a value that may be absent: Some(value) or None. At runtime those are {:some, value} and :none. Some(None) is distinct from None and from nil.

Expected failure uses Result<Success, Error>: Ok(value) or Error(reason). with chains successful results. Each <- expression must produce a Result. The final expression is wrapped in Ok. The first error passes through unchanged.

Use Option for absent values and Result for expected failures. Callers handle these values through pattern matching or with.

Option<A> says a value may be absent. Result<A, E> says a computation may fail with a reason. Both are ordinary ADTs, matched like any other:

mod errors
pub fn unwrap_or(option: Option<Integer>, fallback: Integer) -> Integer {
case option {
Some(value) -> value
None -> fallback
}
}
pub fn double(n: Integer) -> Result<Integer, :badarg> {
with {
value <- parse(n)
value * 2
}
}
fn parse(n: Integer) -> Result<Integer, :badarg> {
if n >= 0 {
Ok(n)
} else {
Error(:badarg)
}
}
pub fn double_or(n: Integer, fallback: Integer) -> Integer {
case double(n) {
Ok(value) -> value
Error(_) -> fallback
}
}

In a with expression, each <- unwraps a Result, the sequence stops at the first Error and returns it unchanged, and the final expression is wrapped in Ok.

One boundary rule: Elixir APIs returning A.t() | nil should be typed as A | nil, not Option<A>. Convert explicitly with gale_std.option.from_nil / to_nil: Some(None), None and nil are three different values, and Gale keeps them that way.

Use string.from_binary to validate UTF-8 before treating bytes as text:

alias gale_std.string
pub fn from_bytes(bytes: Binary) -> Result<String, :invalid_utf8> {
string.from_binary(bytes)
}

with ... else intercepts the first error and rewrites it. The arms match the unwrapped error payload and must themselves return Result, covering every error the chain can produce. Both failure modes below collapse into one :invalid_port; valid ports pass through:

mod errors
alias gale_std.string
fn parse_port(source: String) -> Result<Integer, :not_integer> {
case string.to_integer(source) {
Ok(value) -> Ok(value)
Error(_) -> Error(:not_integer)
}
}
fn valid_port(port: Integer) -> Result<Integer, :out_of_range> {
if port > 0 and port <= 65_535 {
Ok(port)
} else {
Error(:out_of_range)
}
}
@doc "with else matches unwrapped errors and returns Result from every arm."
pub fn port(source: String) -> Result<Integer, :invalid_port> {
with {
parsed <- parse_port(source)
checked <- valid_port(parsed)
checked
} else {
:not_integer -> Error(:invalid_port)
:out_of_range -> Error(:invalid_port)
}
}
@doc "Never has no values, so only Ok is possible here."
pub fn unwrap_infallible<A>(result: Result<A, Never>) -> A {
case result {
Ok(value) -> value
}
}

An infallible Result has error type Never, so it cannot contain Error. The last function therefore needs only an Ok arm.

Use with for dependent operations that would otherwise nest case expressions. If stages need different failure handling, adapt each error before chaining or extract a named helper for that branch. A single case remains useful when success and failure need different responses.

Use gale_std.validation to collect failures from independent checks. The decoding chapter shows how to combine structured error lists.

An Error payload can also be a named exception value with fields and an Elixir-compatible message. The next chapter shows how to construct and match one, and how to catch declared native exceptions.

Linked-process exits, resource exhaustion, and defects inside trusted foreign functions keep their native runtime behavior. Declared checked boundaries (native arithmetic, selected I/O and OTP calls) return Results, extern raises ... turns declared exceptions into typed errors (externs), and untrusted Term input must be decoded before use. Never in a signature means “no normal return”, never an instruction to kill a process.