errors

heliaAOT Errors API

Typed error hierarchy for user-facing failures. A HeliaAotError carries an optional hint (one actionable next step) and optional details (e.g. subprocess output); the CLI renders these as a clean Error: line with a dim hint instead of a traceback, and exits with the error’s exit_code.

Machine-readable model

HeliaAotErrorclassBase class for user-facing heliaAOT failures.
ModelLoadErrorclassThe input model could not be found or read.
OutputExistsErrorclassAn output path already exists and --force was not given.
ConfigValueErrorclassA configuration value is invalid for the requested conversion.
InvalidConfigErrorclassA setting is rejected on its own, against the model or against the target.
UnsupportedModelErrorclassThe input model uses a structure or dtype heliaAOT cannot lower.
OperatorOrderErrorclassAn operator reads a tensor that a later operator produces.
OperatorIdErrorclassAn operator id is not one the generated C can use.
TemplateRenderErrorclassA codegen template referenced context its handler did not supply.
GoldenDataKeyErrorclassA supplied golden-data archive is missing a required tensor key.
GoldenDataNotFoundErrorclassAn explicitly supplied golden-data archive could not be found.
GoldenDataErrorclassSupplied golden data is invalid.
RegistryFrozenErrorclassA frozen registry, or a context that does not allow overrides, was changed.
DuplicateRegistrationErrorclassA registry or the platform registry already holds the key.
ReferenceExecutionErrorclassAutomatic reference setup, execution or worker communication failed.

HeliaAotError(message: str, *, hint: str | None = None, details: str | None = None)

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.

Parameters

Parameters of HeliaAotError
Name	Type	Default	Description
`message`	`str`	Required	What went wrong, phrased for the user.
`hint`	`str \| None`	None	One actionable next step (rendered dim below the error).
`details`	`str \| None`	None	Supporting output (e.g. tool stderr), rendered dim.

exit_code: int = 1

The command line’s exit status for this error.

hint = hint

details = details

ModelLoadError()

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.

exit_code = 2

OutputExistsError()

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.

exit_code = 2

ConfigValueError()

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.

InvalidConfigError()

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.

exit_code = 2

UnsupportedModelError()

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.

OperatorOrderError()

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.

OperatorIdError()

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.

TemplateRenderError()

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.

GoldenDataKeyError()

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.

exit_code = 2

GoldenDataNotFoundError()

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.

exit_code = 2

GoldenDataError()

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.

exit_code = 2

RegistryFrozenError()

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.

DuplicateRegistrationError()

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.

ReferenceExecutionError()

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.