CUDA Error Handling: A Definitive Guide (parallelprogrammer.substack.com)

The CUDA Handbook presents a clear, opinionated approach to CUDA error handling: check every API return code, use a single goto-based Error label for cleanup, and deliberately skip checking error returns from resource-freeing calls. That approach aims to be concise, correct, and easily portable to AMD’s HIP by using macros that prepend “cuda” (or “hip”) to API calls and funnel failures into a single status variable and an Error label. The Handbook also cautions against routine use of cudaGetLastError() (only required for misconfigured kernel launches) and recommends using cudaDeviceSynchronize() to detect runtime kernel faults. Technically, the pattern looks like defining a macro that assigns cuda##fn to status, prints diagnostic info on failure, then jumps to Error for deterministic teardown; resource handles must be initialized (e.g., set event to 0) so cleanup is safe, and cudaFree()/stream destroy calls should not be used to gate further error logic. This yields much less noisy call sites and makes long sequences of allocations and launches readable while ensuring correct propagation of errors. The Handbook’s headers also show how to “stealth HIPify” by switching macros and translating constants, but warns this requires careful preprocessor or source-transformation work. The takeaway: adopt consistent, minimal, auditable error-handling macros and periodically audit CUDA code for missed or excessive checks.