Home / Docs / Language guide / Errors

fail

Release v0.4.0Edition 0.1 and laterU3009U4002U6001U6003

What it does

fail V ends the current function with a failure: the value V, a variant (one of the named alternatives of a kind) of the function's error kind (the kind that lists the ways the function may fail). There is no implicit propagation: the caller receives the failure at the line of the call, and must handle it there.

Learn more: Declaring a failure: fails and fail.

una
module shop

pub kind OrderError = | TooMany

pub add_units(units: Int) -> Int
  fails OrderError
=
  if units > 100 then fail TooMany else units + 1

Forms

In the grammar below, each rule gives a name, =, what the name stands for and ;, quoted words are written as shown, NEWLINE, INDENT and DEDENT stand for a line break and for one more or one less level of indentation, [ ] marks an optional part, { } a part that may repeat, | separates alternatives, ( ) groups them, and (* *) holds a comment.

ebnf
fail_expr       = "fail" variant_expr ;
variant_expr    = upper_ident [ call_args ] ;

fail is an expression, so it may stand where a value is expected: a branch of if, an arm of when, or a block's final expression. The other branches give the value.

Examples

A variant with a payload:

una
module shop

pub kind QuantityError = TooMany(limit: Int) | Negative

pub quantity(units: Int) -> Int
  fails QuantityError
=
  if units > 100 then fail TooMany(limit: 100) else if units < 0 then fail Negative else units

An arm of when may fail, so a binding takes the value of the arms that do not:

una
module shop

pub kind Unreadable = | NotANumber

--- The price in cents that a JSON value holds.
pub price(j: Json) -> Int
  fails Unreadable
=
  let cents = when j
    is Number(value) -> value
    else -> fail NotANumber
  cents

In the branch that does not fail, the verifier (the part of una check that proves facts about the code) knows the negation of the condition, so a guard with fail can establish a precondition (a condition that must hold when a function is called):

una
module shop

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)

A function without fails cannot fail:

una
-- fails with U3009
module shop

pub kind OrderError = | TooMany

pub add_units(units: Int) -> Int = if units > 100 then fail TooMany else units

Edge cases

The variant must belong to the function's error kind:

una
-- fails with U3009
module shop

pub kind OrderError = | TooMany

pub kind PaymentError = | Declined

pub add_units(units: Int) -> Int
  fails OrderError
=
  if units > 100 then fail Declined else units

No failure that depends on labeled data. fail is allowed only when the Branches and failures: implicit flows (the label of the conditions that decided whether this line runs) is public, since whether a function fails is observable. Code that must decide on labeled data returns a labeled value instead:

una
-- fails with U4002
module shop

pub kind CreditError = | OverLimit

pub spend(balance: secret Int) -> secret Int
  fails CreditError
=
  if balance > 100 then fail OverLimit else balance

Further rules:

Diagnostics

Edition

fail is the same in editions 0.1 and 0.2.

Normative source