fix(cuda.core): surface CUresult when graph instantiation fails

[lijinf2]

Description

closes #2527

The Orin nightly failure is test_graph_alloc_with_output: it allocates graph memory, leaves it unfreed so the buffer can be used outside the graph, and instantiates with GraphCompleteOptions(auto_free_on_launch=True). That combination is rejected on L4T Orin (CUDA_ERROR_INVALID_VALUE). Other auto_free_on_launch cases on the same board still pass (empty graphs, alloc+free in the same graph). The test already skips on CUDAError whose message contains CUDA_ERROR_INVALID_VALUE.

After #2473, _instantiate_graph mapped CUDA_GRAPH_INSTANTIATE_ERROR to a generic RuntimeError and dropped the driver CUresult. The skip no longer matched, so the same platform limitation became a FAIL.

This PR calls HANDLE_RETURN on the instantiate status first. A non-success CUresult is raised as CUDAError with the driver name and message (e.g. CUDA_ERROR_INVALID_VALUE). The generic RuntimeError remains only when that status is CUDA_SUCCESS. Orin goes back to skip; the driver error is no longer swallowed.

Checklist

• New or existing tests cover these changes.
• The documentation is up to date with these changes.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[lijinf2]

/ok to test 6aa629f

[rwgk]

I'm approving, but could you please add the test below, and apply the suggested change to the RuntimeError message before you merge?

diff --git a/cuda_core/tests/graph/test_options.py b/cuda_core/tests/graph/test_options.py
index 391f521b65c..a189eaf9160 100644
--- a/cuda_core/tests/graph/test_options.py
+++ b/cuda_core/tests/graph/test_options.py
@@ -7,6 +7,7 @@ import pytest
 from helpers.graph_kernels import compile_common_kernels, compile_conditional_kernels

 from cuda.core import Device, LaunchConfig, launch
+from cuda.core._utils.cuda_utils import CUDAError
 from cuda.core.graph import GraphBuilder, GraphCompleteOptions, GraphDebugPrintOptions


@@ -65,6 +66,20 @@ def test_graph_complete_options(init_cuda):
     gb.complete(options).close()


+@pytest.mark.agent_authored(model="gpt-5.6")
+def test_graph_complete_invalid_options_raise_cuda_error(init_cuda):
+    mod = compile_common_kernels()
+    empty_kernel = mod.get_kernel("empty_kernel")
+
+    gb = Device().create_graph_builder().begin_building()
+    launch(gb, LaunchConfig(grid=1, block=1), empty_kernel)
+    gb.end_building()
+
+    options = GraphCompleteOptions(auto_free_on_launch=True, device_launch=True)
+    with pytest.raises(CUDAError, match="CUDA_ERROR_INVALID_VALUE"):
+        gb.complete(options)
+
+
 def test_graph_build_mode(init_cuda):
     mod = compile_common_kernels()
     empty_kernel = mod.get_kernel("empty_kernel")

[lijinf2]

/ok to test 6283221

[lijinf2]

I'm approving, but could you please add the test below, and apply the suggested change to the RuntimeError message before you merge?

diff --git a/cuda_core/tests/graph/test_options.py b/cuda_core/tests/graph/test_options.py
index 391f521b65c..a189eaf9160 100644
--- a/cuda_core/tests/graph/test_options.py
+++ b/cuda_core/tests/graph/test_options.py
@@ -7,6 +7,7 @@ import pytest
 from helpers.graph_kernels import compile_common_kernels, compile_conditional_kernels

 from cuda.core import Device, LaunchConfig, launch
+from cuda.core._utils.cuda_utils import CUDAError
 from cuda.core.graph import GraphBuilder, GraphCompleteOptions, GraphDebugPrintOptions


@@ -65,6 +66,20 @@ def test_graph_complete_options(init_cuda):
     gb.complete(options).close()


+@pytest.mark.agent_authored(model="gpt-5.6")
+def test_graph_complete_invalid_options_raise_cuda_error(init_cuda):
+    mod = compile_common_kernels()
+    empty_kernel = mod.get_kernel("empty_kernel")
+
+    gb = Device().create_graph_builder().begin_building()
+    launch(gb, LaunchConfig(grid=1, block=1), empty_kernel)
+    gb.end_building()
+
+    options = GraphCompleteOptions(auto_free_on_launch=True, device_launch=True)
+    with pytest.raises(CUDAError, match="CUDA_ERROR_INVALID_VALUE"):
+        gb.complete(options)
+
+
 def test_graph_build_mode(init_cuda):
     mod = compile_common_kernels()
     empty_kernel = mod.get_kernel("empty_kernel")

Sure. The error message becomes more accurate, and test coverage gets improved. I applied all the suggested edits. Thank you Ralf!

[github-actions]

Doc Preview CI
Preview removed because the pull request was closed or merged.