Skip to content

Error Codes

Every C++ entry point (other than helpers such as HaDataTypeBits() and the string conversions below) returns HaError. Codes are stable across releases, and a code is never reused with a different meaning.

Classification and handling are described in Error Handling.


Encoding

The category is carried in the upper bits, so you can branch on the kind of failure without listing every code.

Category Encoding Value
Success 0 0
Common code 1 – 65535
Device (1 << 16) \| code 0x1_0000 and above
Memory (2 << 16) \| code 0x2_0000 and above
Kernel (3 << 16) \| code 0x3_0000 and above
Stream (4 << 16) \| code 0x4_0000 and above
Event (5 << 16) \| code 0x5_0000 and above

Common

Code Name Cause Action
0 HaSuccess — —
1 HaInvalidArgument A device-independent argument is out of range or a null pointer Check the arguments against the signature
2 HaNotSupported The API, option, or execution path is not supported Check the Support Matrix
3 HaTimeout Did not complete within the time limit Check for a kernel that does not terminate. See Troubleshooting
4 HaInternalError Unexpected runtime state This is a defect. Collect logs and report it
5 HaUnknownError Unclassified failure This is a defect. Collect logs and report it

Device

Code Name Cause Action
HaDeviceError \| 1 HaDeviceNotAvailable The device does not exist or cannot be opened Check that ha.ko is loaded and that /dev/ha* is accessible
HaDeviceError \| 2 HaDeviceNotInitialized The device exists but is inactive (for example, not refreshed after HaResetAllDevices() on another thread). VMM: a mapping was called before HaVmmInitBlocks() Call HaSetDevice() again on that thread. For VMM, follow the call order
HaDeviceError \| 3 HaDeviceNotReady Initialization, reset, or loading is in progress Retry after the in-progress operation finishes
HaDeviceError \| 4 HaDeviceInvalidArgument Device ID out of range, a null pointer, or the calling thread has no current device at all (HaSetDevice() was never called) Validate the ID with HaGetDeviceCount(), or call HaSetDevice() on that thread first
HaDeviceError \| 5 HaDeviceAlreadyInitialized Already initialized Not an error in most flows. Ignore it or restructure initialization
HaDeviceError \| 6 HaDeviceOpenFailed The driver rejected to open the device Check device node permissions and whether another process holds the device
HaDeviceError \| 7 HaDeviceCloseFailed Close failed Collect logs and report it
HaDeviceError \| 8 HaDeviceResetFailed Reset failed Reinitialization at the driver level may be required
HaDeviceError \| 10 HaDeviceUnsupported The device, version, or feature is not supported Check the Support Matrix
HaDeviceError \| 11 HaDeviceRegisterSetFailed Setting a device register failed Check the paging configuration; the device often rejects it
HaDeviceError \| 12 HaDeviceInvalidValue The device returned a value the runtime cannot interpret Collect logs and report it
HaDeviceError \| 13 HaDeviceBusy The device is still in use. For example, ha_drv_deinit() was called while device handles remain open Close all handles with ha_drv_close() and call again

Memory

Code Name Cause Action
HaMemoryError \| 1 HaMemoryInvalidAddress Host/device pointer mismatch or a null device pointer Check that the direction argument matches the pointers passed
HaMemoryError \| 2 HaMemoryAlignmentError Alignment constraint violated Check the DRAM alignment rules in the Memory Model
HaMemoryError \| 3 HaMemoryInvalidArgument Invalid size, null pointer, or layout rank/shape mismatch. VMM: the mapping's block_size is not 1, row_indices is missing or outside 0–1023, or pool_base is not 4 KiB aligned HaMemCpyNd() does not broadcast. Both sides must have the same rank and shape. For VMM, check the argument descriptions in the VMM API
HaMemoryError \| 4 HaMemoryAllocationFailed Out of memory or no block satisfies the constraints. VMM: pool_bytes is smaller than the K+V pages of one request Allocate large buffers once at startup. See Troubleshooting. For VMM, enlarge the pool
HaMemoryError \| 5 HaMemoryFreeFailed Free failed Check that the pointer came from an allocation and was not already freed
HaMemoryError \| 6 HaMemoryCopyFailed Transfer failed Treat the destination as partially written
HaMemoryError \| 7 HaMemCpyNotSupported Unsupported copy combination. For example, a device-to-device N-D transfer below the minimum size Route through the host, or use LCCL for collectives
HaMemoryError \| 8 HaHostMemLimitExceeded A configured limit (HA_HOST_MEM_MAX_BYTES, HA_MEMCPYND_STAGING_MAX_BYTES) rejected a host memory allocation. System memory exhaustion is HaMemoryAllocationFailed Raise the limit in Environment Variables, or free host memory that is no longer in use

Kernel

Code Name Cause Action
HaKernelError \| 1 HaKernelInvalidArgument The argument list does not fit the kernel (kind, count, or route), a moved-from argument list, or an invalid kernel binary or library data Compare the expected and passed layouts recorded in the log. For argument list rules, see Execution API
HaKernelError \| 2 HaKernelUnsupported The kernel or execution path is not supported Check the Support Matrix
HaKernelError \| 3 HaKernelExecutionFailed The kernel ran and failed, or a device fault occurred Device state is not guaranteed. Do not retry in place
HaKernelError \| 4 HaKernelNotFound The kernel binary path does not resolve, or the kernel library has no kernel with that name Check the path relative to the process working directory. For library kernels, check the name
HaKernelError \| 5 HaKernelInvalidHandle The kernel handle was released, invalidated by a device reset, or never loaded. Or a library or library kernel handle was not returned by HaLibraryLoadData() or HaLibraryGetKernel() (driver API: ha_drv_library_*) In the driver API, reload with ha_drv_kernel_load_from_file() or ha_drv_kernel_load_from_library(). Pass library handles exactly as issued
HaKernelError \| 6 HaKernelNoBinaryForDevice The kernel library has no kernel binary for the chip generation of the launch device Rebuild the library to include that device version
HaKernelError \| 7 HaKernelLoadFailed The device failed to load the kernel (for a reason other than running out of kernel memory) Check the device state. Running out of kernel memory is HaMemoryAllocationFailed

Stream

Code Name Cause Action
HaStreamError \| 1 HaStreamInvalidHandle Unknown or stale stream handle A device reset invalidates streams
HaStreamError \| 2 HaStreamInvalidArgument Invalid stream argument
HaStreamError \| 3 HaStreamCreationFailed Creation failed The limit is 10 per device
HaStreamError \| 4 HaStreamDestroyFailed Destruction failed Synchronize before destroying
HaStreamError \| 5 HaStreamSyncFailed Synchronization failed Work on the stream failed. Check the preceding operation
HaStreamError \| 6 HaStreamNotReady Not an error. HaStreamQuery() reports that work is in progress Poll again

Event

Code Name Cause Action
HaEventError \| 1 HaEventInvalidHandle Unknown or stale event handle A device reset invalidates events
HaEventError \| 2 HaEventInvalidArgument Invalid event argument
HaEventError \| 3 HaEventCreationFailed Creation failed
HaEventError \| 4 HaEventDestroyFailed Destruction failed Do not destroy an event a stream is waiting on
HaEventError \| 5 HaEventNotRecorded Not an error. HaEventRecord() has never been called on this event Record before waiting or querying
HaEventError \| 6 HaEventNotReady Not an error. HaEventQuery() reports that the event is incomplete Poll again

Three codes are normal control flow

HaStreamNotReady, HaEventNotReady, and HaEventNotRecorded are values that query entry points use to report state. A polling loop that treats every nonzero return as a fatal error stops on the first iteration.


Error name strings

HaError is a bit-packed value, so its integer value is hard to interpret (e.g. err=131078). Get a string with the two functions of the public header ha_error.h. Both are in the lpu::runtime namespace.

Function Returns
const char *HaErrorName(HaError err) The enumerator name (e.g. "HaMemoryCopyFailed"), stable enough for tests and log scrapers to match on. "HaUnrecognizedError" for a value outside the enum
const char *HaErrorToString(HaError err) A human-readable description
1
2
3
4
5
6
#include "ha_error.h"

HaError err = HaMemCpy(dst, src, size, HaMemCpyDirection::HostToDevice);
if (err != HaError::HaSuccess) {
  std::fprintf(stderr, "copy failed: %s\n", lpu::runtime::HaErrorName(err));
}

Python functions of the hart module raise RuntimeError on failure, with a message of the form <failed call>: <error name> (err=<integer value>).


See also