Skip to content

[Fix] Raise Python exceptions instead of exiting on CUDA errors - #13

Open
morluto wants to merge 4 commits into
MoonshotAI:masterfrom
morluto:codex/cpp-error-propagation
Open

[Fix] Raise Python exceptions instead of exiting on CUDA errors#13
morluto wants to merge 4 commits into
MoonshotAI:masterfrom
morluto:codex/cpp-error-propagation

Conversation

@morluto

@morluto morluto commented Jul 28, 2026

Copy link
Copy Markdown

Fixes #9.

Summary

Replace process-terminating CUDA checks in the C++ extension with
Python-visible exceptions, and add exception-safe rollback for partially
acquired VMM resources.

Before: Python --> pybind --> CUDA error --> exit --> process ends

After:  Python --> pybind --> CUDA error --> RuntimeError
                                  |
                                  `--> scoped VMM rollback

Problem

The extension's CUCHECK and CUDACHECK macros printed an error and called
exit(EXIT_FAILURE).

Any checked CUDA driver or runtime failure therefore terminated the entire
Python process from inside the library. Callers could not catch the failure,
add operation context, clean up their own state, or coordinate an orderly
distributed shutdown.

Change

Use TORCH_CHECK to propagate CUDA failures through pybind as RuntimeError.

Error messages now include:

  • the failed CUDA expression;
  • the symbolic error name;
  • the numeric error code;
  • the CUDA error description.

Because failures now unwind the C++ stack, scoped cleanup covers:

  • exported POSIX file descriptors;
  • physical allocation handles;
  • multicast handles;
  • reserved virtual addresses;
  • completed VMM mappings.

Ownership transfers only after the receiving tensor or return tuple is fully
constructed. Imported CUDA handles receive exactly one release attempt before
any release error is propagated; unwind cleanup does not retry an opaque handle
whose release status may reflect an earlier asynchronous CUDA error.

nvl_multicast_bind_map now explicitly documents that it consumes the
multicast handle and borrows the physical allocation handle.

Regression coverage

The regression opens /dev/null as a valid POSIX file descriptor and passes it
to nvl_multicast_import. The descriptor is valid at the OS boundary but is
not a CUDA-exported shareable allocation.

The call runs in a subprocess so any accidental exit() is observable without
terminating pytest.

On an H100 NVL:

  • origin/master — the child process exited with status 1 inside the old CUDA
    check path;
  • exception-propagation implementation — Python caught RuntimeError, verified the failed CUDA
    expression, and continued;
  • final result — 1 passed in 1.74s.

The test intentionally avoids fabricated CUDA allocation handles, whose
invalid use is undefined.

Compatibility

Successful return values, ownership contracts, tensor layouts, and kernel ABI
are unchanged.

Failure behavior changes from unconditional process termination to a catchable
Python exception.

Validation

  • The exception-propagation implementation was rebuilt successfully on an NVIDIA H100 NVL.
  • python3 -m pytest -q tests/test_cpp_error_propagation.py — 1 passed in
    1.74s.
  • git diff --check origin/master...HEAD — passed.

@morluto morluto changed the title Raise Python exceptions for CUDA extension failures [Fix] Raise Python exceptions instead of exiting on CUDA errors Jul 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug] CUDA extension failures terminate the Python process

1 participant