Home / Docs / Specification

06. Errors

Release v0.4.0

Status: Normative, v0.1.

Errors are values. There are no exceptions, no panics and no implicit propagation: every failure is declared in a header and handled at the line where it can occur.

1. Error kinds

Any sum kind can be an error kind. A function declares at most one: fails CheckInError.

una
pub kind CheckInError = NotRegistered | Unavailable(reason: Text)
pub kind StoreError = Timeout | Corrupted

2. Failing

fail V or fail V(field: value) ends the current function with a failure. V MUST be a variant of the function's error kind (U3009). Failing under a program-counter label above public is restricted by spec/07 §3.

3. Handling clauses

A statement whose expression can fail MUST be followed by an if error clause (U3007), unless the expression is wrapped in attempt (§5).

Clause Applies to Meaning
if error fail V(...) Any fallible expression Any failure becomes V. Inside the arguments, error names the original failure value.
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 of the expression's type; error is in scope in e
if none fail V(...) Expression of type Option[T] None becomes failure V; the result has type T
if none use e Expression of type Option[T] None becomes e; the result has type T

Each clause appears at most once per statement, if error before if none (U0102).

(v0.3, ADR 0100.) In edition 0.3, an if error clause MUST NOT follow an expression that cannot fail (U3025): an expression whose failure type is absent once the inferred kinds are final (spec/04 §5 rule 3), or one wrapped in attempt. The diagnostic is at if. Its repair deletes the clause, and una fix applies it. A dead clause never runs, so its own U3008 or U3009 is not reported: U3025 is. Its fail V still decides an inferred kind. A call stays live, and its clause is not U3025, when:

U3025 and U3026 (§5) are judged:

U3025 and U3026 never suppress each other. Editions 0.1 and 0.2 accept these clauses.

una
let registration = @registrations.find(key)
  if error fail Unavailable(reason: "store")
  if none fail NotRegistered

4. Declared failures at the boundary

Failures do not carry postconditions (spec/04 §2). A failure payload's labels follow normal flow rules: a failure raised in a secret context carries that label (spec/07 §3).

5. attempt

attempt f(args) evaluates a single fallible call and returns Result[T, E] instead of failing, so the caller can branch on the outcome:

una
let outcome = attempt @registrations.find(key)
when outcome
  is Ok(value) -> value.is_some()
  is Err(failure) -> false

The operand of attempt MUST be one call (U2001 otherwise). attempt counts as the handling site for U3007.

(v0.3, ADR 0100.) In edition 0.3, the operand of attempt MUST be a call that can fail (U3026), judged as U3025 is (§3). The repair describes how to remove attempt and unwrap the uses of the Result. It carries no edit. In editions 0.1 and 0.2, the Result of an attempt of a call that cannot fail has an unconstrained error type.

6. checked

checked(v, p) else fail V evaluates predicate p at runtime with it bound to v.

checked is an escape hatch: it replaces a static proof with a runtime test. A module uses checked at most [escape_budget] checked_per_module times (0 by default, and for a single file); the first use beyond the budget is U7003, with the later uses as related spans (ADR 0028). Every use is listed in the build report.

7. What is not a failure