---
title: "Errors"
url: https://una-lang.org/en/docs/language/errors/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/guide/syntax-reference.md
---

# 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`.

```una
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).

```una
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 error` comes before `if none` (U0102).
- `error` is valid only inside these clauses (U2013).

```una
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
  found
```

## 6.4 `attempt`

`attempt` turns a single fallible call into a `Result`, so you can branch on the outcome instead of failing:

```una
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) -> false
```

The 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:

`una.toml`

```toml
[package]
name = "phones"
version = "0.1.0"
edition = "0.2"

[escape_budget]
checked_per_module = 1
```

`src/phones.una`

```una
module 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 `v` with its type refined by `p`. This is how opaque facts are established.
- If it fails, the function fails with `V`.
- `p` must be RL or an opaque predicate call, so it can run.
- `checked` replaces a proof with a runtime test, so it is **budgeted**: `[escape_budget] checked_per_module` in `una.toml`, default 0 (U7003 when exceeded). Every use is listed in the build report. A narrowing integer conversion can go through `checked` too, 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.

---


## Constructs

- [fails](https://una-lang.org/en/docs/language/errors/fails.md)
- [fail](https://una-lang.org/en/docs/language/errors/fail.md)
- [if error and if none](https://una-lang.org/en/docs/language/errors/if-error.md)
- [attempt](https://una-lang.org/en/docs/language/errors/attempt.md)
- [checked and the escape budget](https://una-lang.org/en/docs/language/errors/checked.md)
