Documentation Index
Fetch the complete documentation index at: https://mintlify.com/akhildevelops/cudaz/llms.txt
Use this file to discover all available pages before exploring further.
Every C-level error code returned by the CUDA driver, NVRTC compiler, or cuRAND library is automatically converted into a typed Zig error by cudaz’s error.zig module. This means you never inspect raw integer codes—instead you use the familiar try and catch |err| syntax, and the compiler can exhaustively check which errors you’ve handled.
Error Types
cudaz defines three separate error sets, one per underlying C library:
| Zig type | Source library | C constant prefix |
|---|
CudaError.Error | CUDA driver (libcuda) | CUDA_ERROR_* |
NvrtcError.Error | NVRTC compiler (libnvrtc) | NVRTC_ERROR_* |
CurandError.Error | cuRAND (libcurand) | CURAND_STATUS_* |
lib.zig re-exports a combined union type:
pub const CudaError = Error.CurandError.Error || Error.NvrtcError.Error;
Cuda.CudaError is the union of cuRAND and NVRTC errors only. It does not include CUDA driver errors (CUDA_ERROR_*), which are accessed internally as Error.CudaError.Error. Use Cuda.CudaError when you want a single type that covers both compiler and RNG failures.
How Errors Are Generated
error.zig uses Zig’s comptime reflection to introspect the @cImport-ed C headers at compile time. It scans every declaration in the imported namespace, filters those whose names start with the relevant prefix (CUDA_ERROR, NVRTC_ERROR, or CURAND_STATUS), builds an enum from the matching names and values, and finally converts that enum to a Zig error set via the EnumToError utility. The result is a Zig error set whose member names are identical to the C constants—so CUDA_ERROR_INVALID_VALUE in C becomes error.CUDA_ERROR_INVALID_VALUE in Zig, with no hand-written mapping required.
Common CUDA Driver Errors
These originate from CudaError.Error and arise from Device, Module, Function, and memory-management calls:
| Error | Typical cause |
|---|
CUDA_ERROR_INVALID_VALUE | A parameter was out of range or of the wrong type (e.g., bad GPU ordinal passed to Device.new). |
CUDA_ERROR_OUT_OF_MEMORY | The device has insufficient memory for the requested allocation. |
CUDA_ERROR_NOT_INITIALIZED | cuInit was not called before making a driver API call. |
CUDA_ERROR_INVALID_CONTEXT | There is no current CUDA context on the calling thread. |
Common NVRTC Errors
These originate from NvrtcError.Error and arise from Compile.cudaText, Compile.cudaFile, and Compile.cudaProgram:
| Error | Typical cause |
|---|
NVRTC_ERROR_COMPILATION | The CUDA C source contained syntax or type errors. cudaz prints the full compiler log to stderr, then a subsequent NVRTC error is returned when PTX retrieval fails. |
NVRTC_ERROR_OUT_OF_MEMORY | The NVRTC compiler ran out of host memory during compilation. |
Common cuRAND Errors
These originate from CurandError.Error and arise from Rng.default, Rng.init, and Rng.genrandom:
| Error | Typical cause |
|---|
CURAND_STATUS_VERSION_MISMATCH | The cuRAND header and shared library versions do not match. |
CURAND_STATUS_NOT_INITIALIZED | The generator handle was not properly created before use. |
CURAND_STATUS_LAUNCH_FAILURE | The underlying GPU kernel launched by cuRAND failed to execute. |
Error Handling Example
Use catch |err| with a switch to handle specific cases and let unexpected errors propagate:
const device = Cuda.Device.default() catch |err| {
switch (err) {
error.CUDA_ERROR_NOT_INITIALIZED => std.debug.print("CUDA not initialized\n", .{}),
error.CUDA_ERROR_INVALID_VALUE => std.debug.print("Invalid GPU ordinal\n", .{}),
else => return err,
}
return;
};
try is usually sufficient—errors propagate automatically until you reach a boundary where user-facing messages make sense.
Compilation Error Log
When Compile.cudaText or Compile.cudaFile encounters an NVRTC_ERROR_COMPILATION, cudaz performs extra work inside cudaProgram before continuing: it calls nvrtcGetProgramLogSize and nvrtcGetProgramLog to retrieve the full diagnostics string, prints it to stderr with std.debug.print, and then frees the log buffer. After printing, cudaProgram returns normally, and the subsequent getPtx call will fail with its own NVRTC error because no PTX was produced. This means you see the precise line numbers and error messages from the NVRTC compiler in your terminal without any additional setup.
const ptx = Cuda.Compile.cudaText(bad_src, .{}, allocator) catch |err| {
// The compiler log (line numbers, messages) is already on stderr.
std.debug.print("Compilation failed: {s}\n", .{@errorName(err)});
return err;
};
Use try throughout your GPU initialization and kernel-launch code and let errors bubble up to main or a top-level handler. Pattern-match there with a switch to produce friendly user-facing messages, keeping hot paths clean and error-handling centralized.