Errors#

Every failure mode in heliaPROFILER raises a subclass of HpxError. Catch HpxError for a catch-all, or a specific subclass to handle one failure category. Most carry an optional hint attribute — a short, human-readable suggestion for how to fix the problem — which is appended automatically when the exception is formatted as a string.

HpxError #

HpxError(message: str, *, hint: str | None = None)

Bases: Exception

Base exception for all heliaPROFILER errors.

ConfigError #

ConfigError(message: str, *, hint: str | None = None)

Bases: HpxError

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

PlatformError #

PlatformError(message: str, *, hint: str | None = None)

Bases: HpxError

Unsupported board/SoC combination or missing platform capability.

EngineError #

EngineError(message: str, *, hint: str | None = None)

Bases: HpxError

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

FirmwareError #

FirmwareError(message: str, *, hint: str | None = None)

Bases: HpxError

Firmware generation failure — template rendering, file I/O.

BuildError #

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

Bases: HpxError

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.

DependencyError #

DependencyError(message: str, *, hint: str | None = None, returncode: int | None = None, details: str | None = None)

Bases: BuildError

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.

VersionError #

VersionError(message: str, *, hint: str | None = None, returncode: int | None = None, details: str | None = None)

Bases: DependencyError

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.

LockError #

LockError(message: str, *, hint: str | None = None, returncode: int | None = None, details: str | None = None)

Bases: DependencyError

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.

NetworkError #

NetworkError(message: str, *, hint: str | None = None, returncode: int | None = None, details: str | None = None)

Bases: BuildError

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.

CaptureError #

CaptureError(message: str, *, hint: str | None = None)

Bases: HpxError

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

DeterministicCaptureError #

DeterministicCaptureError(message: str, *, hint: str | None = None)

Bases: CaptureError

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_power) 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.

PowerError #

PowerError(message: str, *, hint: str | None = None)

Bases: HpxError

Power measurement failure — Joulescope not found, calibration error.

ReportError #

ReportError(message: str, *, hint: str | None = None)

Bases: HpxError

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