# Errors

A failure a user can act on is raised as a `HeliaAotError`. Each one also inherits the standard-library exception that fits it, so code that already catches `ValueError` or `FileNotFoundError` keeps working when it calls the converter directly.

An error may carry a hint: one actionable next step, printed dim under the message when the command line reports the failure. The hint is written where the error is raised rather than on the class, so it is specific to what went wrong and is not listed here.

| Error | Also a |
| --- | --- |
| [ConfigValueError](https://ambiqai.github.io/helia-aot/reference/errors/#configvalueerror) | `ValueError` |
| [GoldenDataKeyError](https://ambiqai.github.io/helia-aot/reference/errors/#goldendatakeyerror) | `KeyError` |
| [HeliaAotError](https://ambiqai.github.io/helia-aot/reference/errors/#heliaaoterror) | `Exception` |
| [ModelLoadError](https://ambiqai.github.io/helia-aot/reference/errors/#modelloaderror) | `FileNotFoundError` |
| [OutputExistsError](https://ambiqai.github.io/helia-aot/reference/errors/#outputexistserror) | `FileExistsError` |
| [TemplateRenderError](https://ambiqai.github.io/helia-aot/reference/errors/#templaterendererror) | `RuntimeError` |
| [UnsupportedModelError](https://ambiqai.github.io/helia-aot/reference/errors/#unsupportedmodelerror) | `ValueError` |

## ConfigValueError

```python
class ConfigValueError(HeliaAotError, ValueError)
```

A configuration value is invalid for the requested conversion.

Also a ``ValueError`` so callers catching the stdlib type keep working.

## GoldenDataKeyError

```python
class GoldenDataKeyError(HeliaAotError, KeyError)
```

A supplied golden-data archive is missing a required tensor key.

Also a ``KeyError`` so callers catching the stdlib type keep working.

## HeliaAotError

```python
class HeliaAotError(Exception)
```

Base class for user-facing heliaAOT failures.

Args:
    message: What went wrong, phrased for the user.
    hint: One actionable next step (rendered dim below the error).
    details: Supporting output (e.g. tool stderr), rendered dim.

## ModelLoadError

```python
class ModelLoadError(HeliaAotError, FileNotFoundError)
```

The input model could not be found or parsed.

Also a ``FileNotFoundError`` so callers catching the stdlib type keep
working.

## OutputExistsError

```python
class OutputExistsError(HeliaAotError, FileExistsError)
```

An output path already exists and ``--force`` was not given.

Also a ``FileExistsError`` so callers catching the stdlib type keep
working.

## TemplateRenderError

```python
class TemplateRenderError(HeliaAotError, RuntimeError)
```

A codegen template referenced context its handler did not supply.

The shared Jinja environment uses ``StrictUndefined``, so an undefined
name, a missing attribute, or an out-of-range index raises during emit
instead of rendering as the empty string. That is always a heliaAOT defect
rather than a user mistake, but it is reachable from a valid model, so the
failure is reported with the operator, template, and line that produced it
and the original ``UndefinedError`` is kept as ``__cause__``. Also a
``RuntimeError`` so callers catching the stdlib type keep working.

## UnsupportedModelError

```python
class UnsupportedModelError(HeliaAotError, ValueError)
```

The input model uses a structure or dtype heliaAOT cannot lower.

Raised when a graph is recognized but cannot be compiled, so the message
can name the recognized construct and the ``hint`` can state the supported
form. Also a ``ValueError`` so callers catching the stdlib type keep
working.