# 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](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/errors.json)

Base exception for all heliaPROFILER errors.

**API tier:** `stable`

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

**API tier:** `stable`

Unsupported board/SoC combination or missing platform capability.

**API tier:** `stable`

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

**API tier:** `stable`

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

**API tier:** `stable`

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`

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

**API tier:** `stable`

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`

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`

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`

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`

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`

Power measurement failure — Joulescope not found, calibration error.

**API tier:** `stable`

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

**API tier:** `stable`

---

Machine-readable: [`errors.json`](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/errors.json) · [`errors.md`](https://ambiqai.github.io/helia-profiler/reference/api/helia_profiler/errors.md), complete and lossless.