Home / Docs / Language guide
Errors
Errors are values. There are no exceptions, no panics and no implicit propagation.
6.1 Error kinds and fails
Any sum kind can serve as an error kind. A function declares at most one, with fails E.
module demo
pub kind CheckInError = NotRegistered | Unavailable
pub kind StoreError = Timeout | Corrupted(detail: Text)6.2 fail
fail V or fail V(field: value) ends the function with a failure. V must be a variant of the function's error kind (U3009).
module demo
pub kind Seats = Int in 0..5000
pub kind Event
name: Text
remaining: Seats
pub kind BookingError = | InvalidCount
pub seats_after(e: Event, count: Int) -> Seats
requires count >= 1
requires count <= e.remaining
=
e.remaining - count
pub book(e: Event, count: Int) -> Seats
fails BookingError
=
if count < 1 or count > e.remaining
fail InvalidCount
else
seats_after(e, count)In the else branch the verifier knows count >= 1 and count <= e.remaining, so the preconditions of seats_after are proven. The second argument uses punning (§4.4).
6.3 Handling clauses
A statement whose expression can fail must be followed by an indented if error clause (U3007), unless it is wrapped in attempt. Each clause stands on its own line, one level below the statement: fetch(id) if error pass on one line is U0101.
| Clause | Applies to | Meaning |
|---|---|---|
if error fail V(...) |
any fallible expression | any failure becomes V; inside the arguments, error is the original failure |
if error pass |
callee error kind equals the current function's | propagate the failure unchanged (U3008 if the kinds differ) |
if error use e |
any fallible expression | recover with value e; error is in scope |
if none fail V(...) |
an expression of type Option[T] |
None becomes failure V; the result has type T |
if none use e |
an expression of type Option[T] |
None becomes e; the result has type T |
- Each clause appears at most once, and
if errorcomes beforeif none(U0102). erroris valid only inside these clauses (U2013).
module demo
pub kind Registration
name: Text
pub kind StoreError = Timeout | Corrupted(detail: Text)
pub kind CheckInError = NotRegistered | Unavailable
pub capability Registrations
op find(key: Text) -> Option[Registration]
fails StoreError
pub capability Store
op read(path: Text) -> Text
fails StoreError
pub capability Cache
op get(key: Text) -> Option[Text]
fails StoreError
pub lookup(key: Text) -> Registration
uses @registrations: Registrations[find]
fails CheckInError
=
let registration = @registrations.find(key)
if error fail Unavailable
if none fail NotRegistered
registration
pub load(path: Text) -> Text
uses @store: Store[read]
fails StoreError
=
let detail = @store.read(path)
if error fail Corrupted(detail: "read failed")
detail
pub cached(key: Text) -> Option[Text]
uses @cache: Cache[get]
=
let found = @cache.get(key)
if error use None
found6.4 attempt
attempt turns a single fallible call into a Result, so you can branch on the outcome instead of failing:
module demo
pub kind Registration
name: Text
pub kind StoreError = | Timeout
pub capability Registrations
op find(key: Text) -> Option[Registration]
fails StoreError
pub registered(key: Text) -> Bool
uses @registrations: Registrations[find]
=
let outcome = attempt @registrations.find(key)
when outcome
is Ok(value) -> value.is_some()
is Err(failure) -> falseThe operand must be one call (U2001), and attempt counts as its handling site.
6.5 checked (escape hatch)
checked(v, p) else fail V tests predicate p at runtime, with it bound to v. The package must allow it in its escape budget:
[package]
name = "phones"
version = "0.1.0"
edition = "0.2"
[escape_budget]
checked_per_module = 1module phones
pub kind Phone = Text where valid_phone(it)
pub kind PhoneError = | Malformed
pub predicate opaque valid_phone(t: Text) -> Bool = t.len == 11 and is_digits(t)
pub parse_phone(raw: Text) -> Phone
fails PhoneError
=
checked(raw, valid_phone(it)) else fail Malformed- If the test passes, the result is
vwith its type refined byp. This is how opaque facts are established. - If it fails, the function fails with
V. pmust be RL or an opaque predicate call, so it can run.checkedreplaces a proof with a runtime test, so it is budgeted:[escape_budget] checked_per_moduleinuna.toml, default 0 (U7003 when exceeded). Every use is listed in the build report. A narrowing integer conversion can go throughcheckedtoo, on the same budget.
6.6 What is not a failure
- Proof obligations never become runtime failures. Division by zero, overflow, refinement violations and broken preconditions are proven absent before the program runs.
- Running out of call depth, stack or memory is runtime diagnostic U6003, not a Una failure.