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 | |
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
ptrafter a failedHaMemAlloc(). - 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 | |
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 | |
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 | |
1 2 3 4 | |
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.
Next Steps¶
- Troubleshooting — Index by symptom
- Error codes — Full list