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.
Every CUDA API call should be wrapped:
// 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));
Kernels don't return errors directly. After a launch, check two things:
// 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.
assert() works in CUDA kernels on devices with compute capability 2.0+:
__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()):
if (threadIdx.x == 0 && blockIdx.x == 0)
printf("First thread: data[0] = %f\n", data[0]);
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) |
compute-sanitizer --tool memcheck ./my_program
compute-sanitizer --tool racecheck ./my_program
| 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 |
For interactive debugging:
# 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
#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