Tooling

Error Handling and Debugging

Error Handling and Debugging

CUDA operations fail silently by default. All CUDA runtime functions return a cudaError_t code; all kernel launches are asynchronous and can't return a value. Building robust CUDA code requires systematic error checking.

Runtime Error Checking

Every CUDA API call should be wrapped:

c
// Convenient macro for CUDA API calls
#define CUDA_CHECK(call)                                                  \
    do {                                                                  \
        cudaError_t err = (call);                                         \
        if (err != cudaSuccess) {                                         \
            fprintf(stderr, "CUDA error at %s:%d — %s\n",               \
                    __FILE__, __LINE__, cudaGetErrorString(err));         \
            exit(EXIT_FAILURE);                                           \
        }                                                                 \
    } while (0)

// Usage:
CUDA_CHECK(cudaMalloc(&d_ptr, bytes));
CUDA_CHECK(cudaMemcpy(d_ptr, h_ptr, bytes, cudaMemcpyHostToDevice));

Kernel Error Checking

Kernels don't return errors directly. After a launch, check two things:

c
// Check launch configuration errors (wrong grid/block size, etc.)
myKernel<<<grid, block>>>(args);
CUDA_CHECK(cudaGetLastError());

// Check errors that occurred during kernel execution
CUDA_CHECK(cudaDeviceSynchronize());

Without cudaDeviceSynchronize(), errors from asynchronous operations may be attributed to the wrong line of code.

Device-Side Assertions

assert() works in CUDA kernels on devices with compute capability 2.0+:

c
__global__ void myKernel(float *data, int n) {
    int i = blockIdx.x * blockDim.x + threadIdx.x;
    assert(i < n);  // triggers cudaErrorAssert if false; printed to stderr
    data[i] *= 2.0f;
}

printf also works in kernels (buffered and flushed at cudaDeviceSynchronize()):

c
if (threadIdx.x == 0 && blockIdx.x == 0)
    printf("First thread: data[0] = %f\n", data[0]);

Compute Sanitizer

NVIDIA's Compute Sanitizer (replaces the deprecated cuda-memcheck) detects:

| Tool | Detects | |---|---| | memcheck | Out-of-bounds access, misaligned access, uninitialized device memory | | racecheck | Shared memory races (missing __syncthreads()) | | initcheck | Use of uninitialized global memory | | synccheck | Illegal barrier usage (__syncthreads() in divergent code) |

bash
compute-sanitizer --tool memcheck ./my_program
compute-sanitizer --tool racecheck ./my_program

Common Bugs

| Bug | Symptom | Fix | |---|---|---| | Missing cudaDeviceSynchronize() | Wrong results; silent failure | Add sync before checking results | | Off-by-one in grid size | Last elements wrong | Use (N + block - 1) / block | | Accessing freed device memory | Crash or garbage | Track allocation lifetime | | Using host pointer on device | Segfault in kernel | Ensure pointer came from cudaMalloc | | Missing __syncthreads() | Race condition in shared memory | Add barrier after shared memory writes | | Divergent __syncthreads() | Deadlock or hang | Never put __syncthreads() inside an if-block that only some threads reach |

CUDA-GDB

For interactive debugging:

bash
# Compile with debug info
nvcc -G -g -o my_program my_program.cu

# Run under CUDA-GDB
cuda-gdb ./my_program

# Key CUDA-GDB commands
(cuda-gdb) cuda thread (0,0,0) block (1,0,0)  # switch to specific thread
(cuda-gdb) info cuda threads                   # list all active threads
(cuda-gdb) print threadIdx.x                  # inspect CUDA built-ins

// CODE EXAMPLE

example.cu
#include <cuda_runtime.h>
#include <cstdio>
#include <cstdlib>

// Wrap every CUDA call with this macro
#define CUDA_CHECK(call)                                               \
    do {                                                               \
        cudaError_t _err = (call);                                     \
        if (_err != cudaSuccess) {                                     \
            fprintf(stderr, "[CUDA] %s:%d error: %s\n",              \
                __FILE__, __LINE__, cudaGetErrorString(_err));        \
            exit(EXIT_FAILURE);                                        \
        }                                                              \
    } while (0)

__global__ void safeKernel(float *data, int n) {
    int i = blockIdx.x * blockDim.x + threadIdx.x;
    // Device-side bounds check — triggers cudaErrorAssert if violated
    assert(i < n);
    data[i] *= 2.0f;
}

int main() {
    const int N = 1024;
    float *d_data;

    CUDA_CHECK(cudaMalloc(&d_data, N * sizeof(float)));

    // Fill with 1s on device using cudaMemset-like approach
    CUDA_CHECK(cudaMemset(d_data, 0, N * sizeof(float)));

    int tpb = 256;
    int blocks = (N + tpb - 1) / tpb;
    safeKernel<<<blocks, tpb>>>(d_data, N);

    // Always check kernel launch AND execution errors
    CUDA_CHECK(cudaGetLastError());
    CUDA_CHECK(cudaDeviceSynchronize());

    float h_result;
    CUDA_CHECK(cudaMemcpy(&h_result, d_data, sizeof(float), cudaMemcpyDeviceToHost));
    printf("data[0] = %f (expected 0.0)\n", h_result);

    CUDA_CHECK(cudaFree(d_data));
    return 0;
}

// TRY IT

GPU execution
main.cu
loading editor…