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

cuda_core/cuda/core/graph/_graph_builder.pyx

@@ -176,6 +176,7 @@ class GraphCompleteOptions:
 def _instantiate_graph(source, options: GraphCompleteOptions | None = None) -> Graph:
     cdef GraphHandle h_graph
     cdef GraphExecHandle h_exec
+    cdef cydriver.CUresult status
 
     if isinstance(source, GraphBuilder):
         GB_check_open(<GraphBuilder>source)
@@ -209,9 +210,14 @@ def _instantiate_graph(source, options: GraphCompleteOptions | None = None) -> G
     # The exec is adopted only when result_out reports success, so the
     # diagnostics below run before the handle is checked.
     h_exec = create_graph_exec_handle(h_graph, &params)
+    status = get_last_error()
     if params.result_out == driver.CUgraphInstantiateResult.CUDA_GRAPH_INSTANTIATE_ERROR:
+        # HANDLE_RETURN raises CUDAError with the CUresult name and message (e.g. CUDA_ERROR_INVALID_VALUE)
+        # when status is not CUDA_SUCCESS.
+        HANDLE_RETURN(status)
         raise RuntimeError(
-            "Instantiation failed for an unexpected reason which is described in the return value of the function."
+            "CUDA graph instantiation failed, but cuGraphInstantiateWithParams "
+            "returned CUDA_SUCCESS; no driver error details are available."
         )
     elif params.result_out == driver.CUgraphInstantiateResult.CUDA_GRAPH_INSTANTIATE_INVALID_STRUCTURE:
         raise RuntimeError("Instantiation failed due to invalid structure, such as cycles.")
@@ -230,7 +236,7 @@ def _instantiate_graph(source, options: GraphCompleteOptions | None = None) -> G
         raise RuntimeError(f"Graph instantiation failed with unexpected error code: {params.result_out}")
 
     if as_cu(h_exec) == NULL:
-        HANDLE_RETURN(get_last_error())
+        HANDLE_RETURN(status)
     return Graph._init(h_exec)
 
 

cuda_core/tests/graph/test_options.py

@@ -7,6 +7,7 @@
 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")