# Reading an error

Every error a public call of MIME gives (`Experiment.build`, a run, `save`, `load`, `verify`, a result's accessors,
the `mime` command) is a MIME error with a code. An error from below (JAX, MADDENING, NumPy, or your own code called
from inside a run) is translated into one, and the error it translates is kept on it.

## What an error says

<!-- mime-fragment: a quoted traceback shown for its form; it carries frames of one machine, so it is not regenerated -->
```text
Traceback (most recent call last; MIME's, JAX's and MADDENING's frames left out):
  File "settle.py", line 20, in <module>
    exp.build()
BuildRefused: the build is refused:
[user] setting.value: interaction drag:ball (drag 0.3.0): spacing is None m, not a length above zero
    why: the mrs rung samples the body's surface with neighbouring samples about spacing apart
    do: write spacing=mm(...), where interaction drag:ball is declared (Drag(...))
    see: https://microrobotica.org/mime/0.3.0/pages/errors/setting.value
The full traceback is in ~/.cache/mime/tracebacks/mime-...-setting.value.txt; MIME_TRACEBACK=full shows it here.
```

- **The frames** are your own: the lines of your script, its modules, a notebook's cells. MIME's, JAX's and
  MADDENING's frames, and those of the libraries they compute with, are left out of what is shown, never out of what
  is kept.
- **The first line of each reason** is its class in brackets, its code, and what happened, in the experiment's own
  names: its things and attached laws (`drag:ball`), never a graph's node.
- **`why`**, where the message does not already say it: one plain sentence.
- **`do`**: what to write instead, as code you can paste where it can be (`spacing=mm(...)`,
  `exp.declare(...)`, `` `mime assets fetch <folder>` ``). Every action names a MIME argument or command; `mime docs
  check` fails one that does not. That check reads an action's shape, not its truth: it cannot tell a real argument
  from a misspelt one, or an action that would work from one that would not, which the tests of each refusal judge.
- **`at`**: the line of yours closer to the cause than the call, where MIME knows one (the line of a controller's
  step that raised, or that branches on a traced value).
- **`see`**: the code's page, which `mime docs build` writes for every code, with each place MIME gives it, in the
  documentation of the MIME version you run (`/mime/<version>/pages/errors/<code>`).

Several reasons are given at once: a build is refused with every reason it found.

**On a terminal, the `mime` command draws a refusal as a block** (the same fields, in words rather than brackets: the
code and whose to fix it, what is wrong, `what to do`, `why`, `where`, and the docs address under it on one line, to
be copied). A pipe, a file, `--plain`, `NO_COLOR` and `TERM=dumb` get the text above, byte for byte, which is what a
program reads.

## The four classes

- **user**: the script can change it. The error says what to write.
- **environment**: something the run needs is missing or different where it runs (a package, a file, a device, the
  network). The error names what to install, fetch or attach.
- **internal**: a check on MIME's own construction, which no supported script should reach. It is MIME's defect: the
  error says so, with the address to report it at and the file to attach. An entry's defect (`entry.defect`) is the
  defect of the package that defines the entry: one a lab registered is named as that package's, at the entry's own
  line that raised, and never called MIME's.
- An error MIME raised with no code (`error.uncoded`) is a gap in MIME's codes, not a fault of yours: its message is
  MIME's own and often says what to change, it keeps its own class (a `KeyError` is still one), and the footer asks
  you to report it so that it gets a code.
- **unrecognised**: an error from below that MIME has no translation for (`error.unrecognised`). It is shown at your
  own line, with the error's own type and message, and it is never called MIME's defect.

## Errors from below, translated

- A Python `if`, `int()` or `float()` on a traced value in a controller's step that runs inside the compiled step:
  `control.law-traced-branch`, at the line of the step that asks, with `jnp.where` (or `jax.lax.cond`) as the fix, or
  the callback mode, where the step may be any Python.
- A controller's step that raises while it runs as a callback, or returns writes of other labels or shapes:
  `control.law-raised` and `control.law-writes`, at the step's line.
- A state that is not finite numbers at the end of a run: `run.non-finite`, naming the first step, thing and field
  where the run kept every step's state (`history=True`), and how to find them where it did not. The run's result is
  kept on the error, as `error.result`.
- A device out of memory, as XLA reports it: `run.out-of-memory`, with what to keep less of. The host's own
  `MemoryError` (an array of your script's too large for the machine) is not the device's: it stays unrecognised, and
  a `MemoryError`.
- A value given without its units, or in units of another dimension, where a call takes a quantity (a bare number
  for a run's duration): `call.units`, a `ValueError` and a `UnitError` as before, with the value written in its unit.
- A folder `save` cannot write into: `save.not-writable`, and still the `OSError` it was. A document that is not
  Unicode text: `load.document-encoding`. A reference outputs file that is truncated or corrupt: `load.reference`.

## Reaching the full traceback

The full chain (every frame from your script's first down to the raise, and every error chained to it) is kept on
the error as `error.chain`, and written to a file when the error is shown: under `tracebacks` in MIME's cache
directory, or under `$MIME_TRACEBACK_DIR` when it is set. The file holds the error, the versions of Python, MIME,
MADDENING, JAX and NumPy, and the chain. Writing one deletes all but the newest, so the directory never grows; delete
it whenever you like.

- **`MIME_TRACEBACK=full`** shows every frame and every chained error in place of the short form, as Python prints
  them. MIME's test suite runs this way.
- **The CLI's `--traceback`**, anywhere on the line, does the same for one command.
- **The file** is written readable by you alone, named `mime-<time>-<process>-<code>.txt`. Only files of that name
  are ever deleted, so `$MIME_TRACEBACK_DIR` may name a folder that holds your own files.

<!-- mime-fragment: a shell line with an environment variable for the reader's own script, which is not in this repository -->
```sh
MIME_TRACEBACK=full python settle.py
mime run <folder> --duration 1s --out run --traceback
```

- **In Jupyter and IPython** the short form is shown for a MIME error a cell does not catch, through the shell's own
  handler of MIME's errors (where the shell has no other); `MIME_TRACEBACK=full` gives IPython's own traceback.
- **A hook of your own** (a crash reporter, an application's error dialog) set as `sys.excepthook` before
  `import mime` still receives MIME's errors, after their short form; one set after MIME's replaces it and receives
  every error itself, MIME's with their short traceback.
- **In a thread**, an uncaught MIME error is shown by Python's own thread handler, with its short traceback (your own
  frames) and no file written: the short form's text and its file are the main thread's.
- **A recursion** in your own code is shown with its repeated frame once and its count, as Python shows it.

## Catching an error in code

Every MIME error is a `mime.errors.MimeError`, with `codes()`, its `refusals` (each with its `code`, `category`,
`message`, `action`, `why` and `where`) and `original`, the error from below it translates. The classes are caught as
they were: `BuildRefused` and its subclasses (`LoadRefused`, `EnvRefused`); an error a run's arguments are refused
with is still a `ValueError` or a `TypeError`; `NotRecorded` and a result that does not hold an observation are
still a `KeyError`; a controller's `ControllerError` and a failed run's `RunFailed` are a `RuntimeError`.

An error from below that a public call translates is also of its own class, so the handler written for it still
catches it: your own exception raised in a hook or a controller's step (`except Done`), an `OSError` from `save`, a
`MemoryError`, a warning your filter raises as an error, and `pytest.raises(ValueError)` in your tests. Its attributes
are kept (`error.errno`, your exception's own); `error.original` is the exception itself. In the rare case where its
class cannot be a base of another (a class that forbids subclasses), the original leaves the call unchanged.

<!-- mime-fragment: a handler in the reader's own script, shown for its shape; names such as Settled and stop_when_settled are the reader's -->
```python
try:
    built.run(s(1), hook=stop_when_settled, chunk=ms(10))
except Settled as done:            # the script's own exception, raised by its hook
    print("settled at", done.time)  # its own attribute
    raise done.original from None   # or the exception itself, with every frame
```

A caught error keeps its short traceback, with your own frames, so `traceback.print_exc()` and `logging.exception`
show them, not MIME's or JAX's. To see below them:

- **`error.chain`**: the full traceback as text, every frame and every chained error, as it was when the error left
  the call; `write_traceback(error)` writes it to a file.
- **`error.original`**: the error from below, whose own `__traceback__` holds every frame below the call:
  `traceback.print_exception(error.original)`, or `pdb.post_mortem(error.original.__traceback__)` to step into MIME's
  and JAX's frames.
- **`MIME_TRACEBACK=full`**, set before the run: the error leaves with every frame and the original chained as its
  cause, so `%debug` and `pdb.pm()` reach every frame.

## The command's exit codes

A refused command prints why, as above but with no frames (you wrote no Python), its first line naming the command
(`mime pull is refused:`, `mime run failed:`), and exits with the code that says whose it is to act on. A
`mime run` whose state is not finite at its end writes its outputs all the same (`outputs.json` and `run.json` say
`non_finite`), then says to run again with `--history` or with a smaller `dt` in the saved document:

<!-- mime-fragment: the exit codes, a table in plain text -->
```text
0  done
1  mime verify: an output moved; mime pending: something is pending
2  refused, for the user's or the environment's reason
3  a MIME defect, or an error MIME does not recognise
```