Skip to content

6. Error Handling

Every C++ entry point returns HaError and does not throw, except the HaLaunchArgs constructor, which throws std::bad_alloc when memory is short. If you discard the return value, the failure passes silently and its consequences show up several steps later as an unrelated symptom. This chapter covers what to check and what you can do after a failure.

The key point is that not all failures are alike. Some are fixed by correcting the arguments and calling again, some require cleaning up resources and retrying, and some mean the device can no longer be trusted. Retrying uniformly based on the return value alone makes things worse in the last case.

Contents

Section Objective
6.1 Return Contract What each function returns and what it does not return
6.2 Failure Categories The criteria that determine how to respond to an error, and how failures are categorized
6.3 Nonzero Does Not Always Mean Failure Identifying return values that are part of normal flow rather than errors
6.4 State After Failure Criteria for deciding whether a retry is possible (transient vs. permanent)
6.5 The First Calls of a Process Failure types that occur only during process startup
6.6 Python Interface How the C/C++ return value scheme is converted into exceptions in the Python layer
6.7 Logging Using logging to see internal state that return values alone do not reveal

The full list of codes is in Error codes, and responses by symptom are in Troubleshooting.


6.1 Return Contract

1
2
3
4
HaError err = HaMemAlloc(&ptr, size, false);
if (err != HaError::HaSuccess) {
    // ptr is not valid
}

This return contract applies to the entire C++ API.

  • The return value is always HaError. Results are passed through pointer parameters.
  • Do not rely on output parameters after a failure. Depending on the cause, they are left unchanged or set to 0. Initialize them yourself, and do not use ptr after a failed HaMemAlloc().
  • Exceptions do not propagate across the API boundary.

6.2 Failure Categories

HaError encodes the failure category in the upper bits of the value, so you can branch on the broad category of a failure without listing every code.

Category Encoding Includes
Success 0
Common 1 – 65535 Invalid argument, unsupported, timeout, internal error
Device (1 << 16) \| code Availability, initialization, open/close/reset
Memory (2 << 16) \| code Address, alignment, allocation, copy
Kernel (3 << 16) \| code Arguments, load, execution
Stream (4 << 16) \| code Handle, create/destroy, synchronization
Event (5 << 16) \| code Handle, record, completion
1
2
constexpr int kMemoryClass = 2;
bool is_memory_error = (static_cast<int>(err) >> 16) == kMemoryClass;

This encoding is stable across versions. It is safe to treat branching by category as the contract and to treat individual code values only as additional diagnostic information.

6.3 Nonzero Does Not Always Mean Failure

The following three codes report query results as part of normal control flow; they are not errors that indicate failure.

Code Returned by Meaning
HaStreamNotReady HaStreamQuery() Work is still in progress
HaEventNotReady HaEventQuery() The event has not completed yet
HaEventNotRecorded HaEventQuery(), HaEventSynchronize() HaEventRecord() has never been called on this event

A polling loop that treats every return value other than HaSuccess as fatal stops on its first iteration. Always check these three codes explicitly and separately.

6.4 State After Failure

Failure Resulting state
HaMemAlloc() returns an error Nothing was allocated and nothing leaked. Do not use the output pointer (it may be set to 0)
HaMemCpy() returns an error The destination may have been partially written. Do not assume it is unchanged
HaLaunchKernel() returns HaKernelExecutionFailed Device state is not guaranteed. Do not assume the kernel output is usable
HaStreamCreate() returns an error No stream was created and the handle is unchanged

There is no HaGetLastError(). The failed call itself tells you.

On retrying a failed launch

HaKernelExecutionFailed does not tell you whether the device is still usable. Retrying the same launch is not a safe recovery strategy. In a serving process, fail the request and surface the error. In a test loop, reset the device before continuing. Note that a reset invalidates all allocations and streams on that device.

6.5 The First Calls of a Process

Failures on the first run of a process are usually one of the following two codes, and each points to a clearly different cause.

Code Cause Action
HaDeviceNotAvailable No device, or the device cannot be opened Check that the KMD is loaded and that the process can access the device node
HaDeviceInvalidArgument This thread has no current device Call HaSetDevice() on that thread first

If everything works on the main thread but HaDeviceInvalidArgument occurs only on worker threads, it is almost always the second case, because the current device is set separately for each thread. See Multi-Device Programming.

6.6 Python Interface

Unlike C++, the Python bindings do not return error codes; they raise an exception on failure.

1
2
3
4
try:
    buf = hart.mem_alloc(size)
except RuntimeError as e:
    ...

The exception message includes the failed call and the name of the HaError code.

hart.mem_free(None) is not an error and does nothing, so cleanup paths do not need a separate guard for it.

6.7 Logging

The runtime logs through the logger shared by all HyperAccel products (halogger). Set the log level and output when diagnosing a failure, and always attach that output when reporting a problem.

1
2
3
4
import halogger

halogger.set_level("warn")         # "trace", "debug", "info", "warn", "error", "critical", "off"
halogger.set_file("hart-debug.log")
1
2
3
4
#include "public/ha_logger.h"

HA_SET_LOG_LEVEL(lpu::logger::LogLevel::Warn);
HA_SET_LOG_FILE("hart-debug.log");

The levels are Trace (0), Debug (1), Info (2, default), Warn (3), Error (4), Critical (5), and Off (6). Python's set_level() takes the level as a lowercase string. In release builds, a level below Warn (Trace, Debug, Info) is applied as Warn.

Also configurable through environment variables

The runtime reads HA_LOG_LEVEL (0–6, same numbers as above), HA_LOG_OUTPUT_MODE (0 console / 1 file), and HA_LOG_PATH on the first Ha* call. Set the environment variables before the runtime reads its initial configuration. If halogger.set_level() or HA_SET_LOG_LEVEL() is called after the environment variable sets the log level, the newly specified log level takes effect.

See Environment variables.


Next Steps