# Errors

> UForm for Mojo

Every fallible entry point raises `Error` and nothing else, since Mojo allows one error type per function.
An `Error` carries a `Status` shared with the C interface, so a fault this binding catches before the boundary reports the status the engine would have reported for the same fault:

```mojo
try:
    _ = Model.load_ram(executor, "missing.safetensors")
except error:
    if error.status == Status.IO:
        pass
    print(error)  # UForm: io [uform_model_load_ram]: ...
```

An `Error` keeps the engine mapped while it lives, since its name and message are the engine's own static text.

`from uform import Status, Error`

## Status

Why a call into the engine failed, the `uform_status_t` vocabulary verbatim.

```mojo
struct Status
```

An [`Error`](#Error) never carries [`SUCCESS`](#SUCCESS) or [`DEFERRED`](#DEFERRED): only a [`Deferred`](https://www.unum.cloud/docs/uform/mojo/receivers-and-deferred-calls.md#Deferred) reports the latter, and only
until its call is final. [`Library.status_name`](https://www.unum.cloud/docs/uform/mojo/design.md#status_name) spells each one as the engine does.

- `SUCCESS` = `Status(Int32(0))`: The call completed.
- `DEFERRED` = `Status(Int32(1))`: The call was submitted deferred and is not final yet; the one non-final status.
- `OUT_OF_MEMORY` = `Status(Int32(2))`: Device, pinned or host memory could not be allocated, or the scratch ceiling is too low.
- `SHAPE_MISMATCH` = `Status(Int32(3))`: Item counts, a pixel shape, or a batch envelope disagree with the call or the model.
- `UNSUPPORTED_LAYOUT` = `Status(Int32(4))`: A stride or packing the model cannot read.
- `UNKNOWN_KIND` = `Status(Int32(5))`: A scalar, modality or name this build does not know.
- `IO` = `Status(Int32(7))`: A checkpoint file could not be opened, read or written.
- `DEVICE` = `Status(Int32(8))`: The driver refused or the device faulted; after a fault the executor refuses every later call.
- `MALFORMED` = `Status(Int32(9))`: Supplied bytes could not be decoded: a checkpoint, an image, a clip or a recording.
- `INTERNAL` = `Status(Int32(10))`: The library reported neither success nor a failure, which names a defect rather than a state.
- `CONFIG_MISMATCH` = `Status(Int32(13))`: The request contradicts a frozen configuration, like resuming a checkpoint of another geometry.
- `CONTENDED` = `Status(Int32(14))`: The call was refused rather than waited for, like a submission to a full deferred table.
- `CANCELLED` = `Status(Int32(15))`: A progress handler asked the call to stop; it unwound and published nothing.
- `UNSUPPORTED` = `Status(Int32(16))`: The verb is declared for every residency or model, but this one does not implement it.
- `INVALID_ARGUMENT` = `Status(Int32(17))`: An argument breaks the verb's contract, like a read of a result whose arena a later call rewound.
- `LIBRARY_MISSING` = `Status(Int32(-1))`: Nothing to `dlopen`, the binding's own.
- `SYMBOL_MISSING` = `Status(Int32(-2))`: The library loaded but does not export a symbol the binding needs, the binding's own.
- `VERSION_MISMATCH` = `Status(Int32(-3))`: The library loaded but reports a different major version than the binding's, the binding's own.
- `code` `Int32`: The raw `uform_status_t` value, kept even when this build does not name it.

Conforms to: `Copyable`, `Deinitable`, `Equatable`, `ImplicitlyCopyable`, `Movable`, `RegisterPassable`, `TrivialRegisterPassable`

## of

Lifts a raw `uform_status_t`, keeping an unnamed one rather than guessing.

```mojo
def of(code: Int32) -> Self
```

## Error

What went wrong inside the engine, and which entry point it was about.

```mojo
struct Error
```

- `status` `Status`: Which class of failure the engine reported.
- `detail` `StaticString`: The entry point it was about, for a reader rather than for a branch.
- `message` `Optional[Pointer[Scalar[_c_char_dtype()], ImmUntrackedOrigin]]`: The engine's own static message, which outlives the call and needs no freeing.
- `name` `Optional[Pointer[Scalar[_c_char_dtype()], ImmUntrackedOrigin]]`: The engine's spelling of [`status`](https://www.unum.cloud/docs/uform/mojo/receivers-and-deferred-calls.md#status), absent where no engine named it.
- `library` `Optional[Library]`: The engine `message` and [`name`](https://www.unum.cloud/docs/uform/mojo/executors.md#name) live in, kept mapped for as long as the error is; Mojo would otherwise unload it at the last handle's last use, while the error is still being read.

Conforms to: `Copyable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`, `Writable`

## __init__

A failure the binding caught before any engine could name it.

```mojo
def __init__(out self, status: Status, detail: StringSpan[ImmStaticOrigin])
```

- `status`: Which class of failure it is.
- `detail`: The entry point or binding type it was about.

## write_to

Writes the status name, the entry point, and the engine's own message together.

```mojo
def write_to(self, mut writer: T)
```

- `writer` (mut): The sink the message is appended to.