Skip to content
heliaPROFILER
Reference
HELIA

errors

The exception hierarchy every heliaPROFILER failure is raised through, rooted at HpxError.

Every name on this page is imported from helia_profiler.

API tier: stable, experimental

Generated from the src/helia_profiler tree fe269596788d6ab1604cf433559e96b5f48c1d13.

Machine-readable model

  • HpxErrorclassBase exception for all heliaPROFILER errors.
  • ConfigErrorclassBad configuration — missing model path, invalid YAML, unknown board.
  • PlatformErrorclassUnsupported board/SoC combination or missing platform capability.
  • EngineErrorclassEngine adapter failure — AOT compile error, missing static lib, etc.
  • FirmwareErrorclassFirmware generation failure — template rendering, file I/O.
  • BuildErrorclassNSX configure / build / flash / lock / sync failure.
  • CaptureErrorclassData capture failure — serial timeout, corrupt data, SWO framing.
  • DeterministicCaptureErrorclassA capture-path refusal no retry or power cycle can change.
  • NetworkErrorclassTransient network failure during sync/lock (git fetch, module download).
  • DependencyErrorclassDeterministic dependency lock/workspace failure (base class).
  • VersionErrorclassA tool, package, engine, or lock schema version is incompatible.
  • LockErrorclassA dependency lock file or its recorded provenance is unusable.
  • PowerErrorclassPower measurement failure — Joulescope not found, calibration error.
  • ReportErrorclassReport generation failure — output path not writable, format error.
class

ConfigError

Python

Bad configuration — missing model path, invalid YAML, unknown board.

src/helia_profiler/errors.py:33

ConfigError()

Bad configuration — missing model path, invalid YAML, unknown board.

API tier: stable

class

EngineError

Python

Engine adapter failure — AOT compile error, missing static lib, etc.

src/helia_profiler/errors.py:41

EngineError()

Engine adapter failure — AOT compile error, missing static lib, etc.

API tier: stable

class

BuildError

Python

NSX configure / build / flash / lock / sync failure.

src/helia_profiler/errors.py:49

BuildError(message: str, *, hint: str | None = None, returncode: int | None = None, details: str | None = None) -> None

NSX configure / build / flash / lock / sync failure.

Carries the underlying tool’s diagnostic output (cmake / ninja / SEGGER commander / git stderr, NSX exception message, etc.) in :attr:details. When the source is a real subprocess, the original return code is also captured in :attr:returncode.

API tier: stable

class

CaptureError

Python

Data capture failure — serial timeout, corrupt data, SWO framing.

src/helia_profiler/errors.py:71

CaptureError()

Data capture failure — serial timeout, corrupt data, SWO framing.

API tier: stable

class

DeterministicCaptureError

Python

A capture-path refusal no retry or power cycle can change.

src/helia_profiler/errors.py:75

DeterministicCaptureError()

A capture-path refusal no retry or power cycle can change.

Subclass of :class:CaptureError so existing except CaptureError handlers still catch it, but recovery paths that would otherwise cycle the target rail and retry (stages.flash.deploy_firmware) re-raise it instead: these are configuration/artifact gaps — a missing image, an unknown load address — and cycling the rail only frames them as flaky hardware.

API tier: stable

class

NetworkError

Python

Transient network failure during sync/lock (git fetch, module download).

src/helia_profiler/errors.py:87

NetworkError()

Transient network failure during sync/lock (git fetch, module download).

Subclass of :class:BuildError so existing except BuildError handlers still catch it, but callers that want to retry can specifically catch this.

API tier: stable

class

DependencyError

Python

Deterministic dependency lock/workspace failure (base class).

src/helia_profiler/errors.py:95

DependencyError()

Deterministic dependency lock/workspace failure (base class).

Covers workspace fingerprinting, override, and provenance-collection failures that are neither a version mismatch nor a lock-file problem. Prefer :class:VersionError or :class:LockError when a failure is specifically about an incompatible version or a missing/corrupt lock.

API tier: experimental

class

VersionError

Python

A tool, package, engine, or lock schema version is incompatible.

src/helia_profiler/errors.py:105

VersionError()

A tool, package, engine, or lock schema version is incompatible.

Raised when an installed version fails a compatibility baseline check (schema version, minimum/maximum engine version, pinned package version) so callers can distinguish “wrong version” from other dependency failures and surface an actionable upgrade/downgrade hint.

API tier: experimental

class

LockError

Python

A dependency lock file or its recorded provenance is unusable.

src/helia_profiler/errors.py:115

LockError()

A dependency lock file or its recorded provenance is unusable.

Raised for a missing, unreadable, structurally invalid, or drifted nsx.lock / hpx-dependencies.json, so field-diagnostics collectors can skip just the lock-provenance section instead of failing an entire report.

API tier: experimental

class

PowerError

Python

Power measurement failure — Joulescope not found, calibration error.

src/helia_profiler/errors.py:125

PowerError()

Power measurement failure — Joulescope not found, calibration error.

API tier: stable

class

ReportError

Python

Report generation failure — output path not writable, format error.

src/helia_profiler/errors.py:129

ReportError()

Report generation failure — output path not writable, format error.

API tier: stable

Machine-readable: errors.json · errors.md, complete and lossless.