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 OSError keeps working when it calls the converter directly. ModelLoadError is an OSError but not a FileNotFoundError, so except FileNotFoundError does not catch a model that cannot be loaded.

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.

When an error ends a command, the command line exits with the error’s exit_code, which its class declares and the table lists; Exit codes says what each code means. A plain ConfigValueError carries 1, for a valid request the model cannot be converted with; a setting rejected on its own, against the model or against the target raises InvalidConfigError, the ConfigValueError subclass that declares 2.

Error	Also a	Exit code
ConfigValueError	ValueError	1
DuplicateRegistrationError	KeyError	1
GoldenDataError	ValueError	2
GoldenDataKeyError	KeyError	2
GoldenDataNotFoundError	FileNotFoundError	2
HeliaAotError	Exception	1
InvalidConfigError	ValueError	2
ModelLoadError	OSError	2
OperatorIdError	ValueError	1
OperatorOrderError	RuntimeError	1
OutputExistsError	FileExistsError	2
ReferenceExecutionError	RuntimeError	1
RegistryFrozenError	RuntimeError	1
TemplateRenderError	RuntimeError	1
UnsupportedModelError	ValueError	1

ConfigValueError

class ConfigValueError(HeliaAotError, ValueError)

A configuration value is invalid for the requested conversion.

Also a ValueError so callers catching the stdlib type keep working. The CLI exits 1: the request is valid but the model cannot be converted with it, such as an operator no kernel applies to. A setting that is itself rejected, on its own, against the model or against the target, is the narrower :class:InvalidConfigError, which exits 2.

DuplicateRegistrationError

class DuplicateRegistrationError(HeliaAotError, KeyError)

A registry or the platform registry already holds the key.

Raised by Registry.register without overwrite and by register_platform for a name already registered in any case. Also a KeyError so callers catching the stdlib type keep working.

GoldenDataError

class GoldenDataError(HeliaAotError, ValueError)

Supplied golden data is invalid.

A supplied archive must be a readable .npz whose input_N and output_N arrays have their tensor’s element count and dtype. The CLI exits 2. Automatic execution failures use ReferenceExecutionError. Also a ValueError so callers catching the stdlib type keep working.

GoldenDataKeyError

class GoldenDataKeyError(HeliaAotError, KeyError)

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

The CLI exits 2: the golden data was rejected. Also a KeyError so callers catching the stdlib type keep working.

GoldenDataNotFoundError

class GoldenDataNotFoundError(HeliaAotError, FileNotFoundError)

An explicitly supplied golden-data archive could not be found.

The CLI exits 2: the golden data was rejected, as for an archive that cannot be read. Also a FileNotFoundError so existing Python callers keep working.

HeliaAotError

class HeliaAotError(Exception)

Base class for user-facing heliaAOT failures.

The class decides how the command line exits, by one rule. A class whose errors mean the user’s input was rejected declares exit_code 2: the command line, the configuration, a file it names (the model, the golden data, the output location), the choice of model type or format, or the target. Every other class keeps 1: a valid request failed while converting, for example a model construct heliaAOT cannot lower, or memory that does not fit. When the check runs does not matter, so input rejected after the model has loaded still exits 2. The command line exits with the exit_code of the error that ended it and reads no other rule.

Attributes: exit_code: The command line’s exit status for this error.

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.

InvalidConfigError

class InvalidConfigError(ConfigValueError)

A setting is rejected on its own, against the model or against the target.

Raised for a file ConvertArgs.from_yaml cannot load, an unknown or removed key or value, a renamed setting under both its keys, a model type or file extension heliaAOT does not read, a model.subgraph the model does not have, an unknown platform, transform or memory planner option, an operators[] attribute key or value no operator the rule reaches takes, a memory constraint or pin the target cannot honour, memory.tensors rules that stage one destination memory from two source memories, a test setting the model cannot take (such as test.state_feedback pairs that are out of range, mismatched or drive one input twice), a module.path, module.name, module.prefix or log_file that cannot be written, a target that cannot run the model (float16 tensors without FP16 support, an Ethos-U operator without an NPU), and an invalid SOURCE_DATE_EPOCH. The CLI exits 2, whether the check runs before or during conversion. A ConfigValueError, so a handler for that class also catches it.

ModelLoadError

class ModelLoadError(HeliaAotError, OSError)

The input model could not be found or read.

Raised for a missing file, a file without read permission, a directory or a git-lfs pointer in place of the model, and a file that is not a readable LiteRT flatbuffer. The CLI exits 2: the model file was rejected. Also an OSError, the stdlib type for a file that cannot be loaded, whether it is missing or unreadable; it is not a FileNotFoundError, which would claim a damaged model is a missing one.

OperatorIdError

class OperatorIdError(HeliaAotError, ValueError)

An operator id is not one the generated C can use.

Code generation names each operator’s C functions and source file by its id, and the plan records it as the operator’s node id, so an id must be the importer’s form: a non-negative decimal integer that fits an int32, without leading zeros, used by no other operator. An id that breaks the rule comes from a custom parser or transform, and is rejected when the operators are resolved instead of emitting C that does not compile or sources that overwrite each other. Also a ValueError so callers catching the stdlib type keep working.

OperatorOrderError

class OperatorOrderError(HeliaAotError, RuntimeError)

An operator reads a tensor that a later operator produces.

The operator list is the execution order the planner and the emitted schedule follow. The check runs on the loaded model and after each graph transform, and the message names the stage, the reading operator, the tensor and its producer. After a built-in transform it is a heliaAOT defect; after a custom transform, that transform broke the order. Also a RuntimeError so callers catching the stdlib type keep working.

OutputExistsError

class OutputExistsError(HeliaAotError, FileExistsError)

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

The CLI exits 2: the output location was rejected. Also a FileExistsError so callers catching the stdlib type keep working.

ReferenceExecutionError

class ReferenceExecutionError(HeliaAotError, RuntimeError)

Automatic reference setup, execution or worker communication failed.

This does not establish that the model or user configuration is invalid. The diagnostic names the phase and preserves available backend tracebacks in details. Native crashes may have no Python traceback. The CLI exits 1. Also a RuntimeError for Python callers handling execution failures.

RegistryFrozenError

class RegistryFrozenError(HeliaAotError, RuntimeError)

A frozen registry, or a context that does not allow overrides, was changed.

Raised by Registry.register, unregister and clear on a frozen registry, and by build_default_registry_context when a customizer replaces or removes a built-in without allow_override. Also a RuntimeError so callers catching the stdlib type keep working.

TemplateRenderError

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

class UnsupportedModelError(ConfigValueError)

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. A ConfigValueError, and so a ValueError: a handler for ConfigValueError also catches it, so a rejection raised as ConfigValueError today can be raised as this narrower class in a later release without escaping that handler.