[srimanachanta]

Closes #3260

Summary

Add cuda.core.CUDAOutOfMemoryError(CUDAError, MemoryError). CUDA_ERROR_OUT_OF_MEMORY and cudaErrorMemoryAllocation now raise it instead of a plain CUDAError.

Motivation

Allocating too much from a DeviceMemoryResource raises CUDAError, which derives only from Exception:

>>> mr.allocate(1 << 46, stream=dev.default_stream)
CUDAError: CUDA_ERROR_OUT_OF_MEMORY: ...
>>> type(e).__mro__
(CUDAError, Exception, BaseException, object)

CuPy (cupy.cuda.memory.OutOfMemoryError) and RMM raise a MemoryError subclass when device memory runs out, and NumPy raises one for host allocations. Code that recovers from running out of memory by asking for less catches MemoryError. A downstream CUDA extension library defines its own CudaOutOfMemory for this reason (common.hpp, registered as a MemoryError in bindings.cpp), and its sweep halves the chunk on except MemoryError (simulation.py). That retry does not see out-of-memory errors from cuda.core.

Change

• _check_driver_error and _check_runtime_error pick CUDAOutOfMemoryError for the two out-of-memory codes. Every driver and runtime failure in cuda.core, including the C++ handle layer through HANDLE_RETURN(get_last_error()), goes through these two functions.
• Message, explanation and notes are unchanged. Code that catches CUDAError is unaffected.
• Exported from cuda.core, added to api.rst, the error handling page and the 1.3.0 release notes.

NVRTC's NVRTC_ERROR_OUT_OF_MEMORY still raises NVRTCError. I left it out to keep the change to driver and runtime errors.

Tests

• Driver and runtime OOM codes raise CUDAOutOfMemoryError, which is both a CUDAError and a MemoryError.
• No other driver or runtime code raises a MemoryError.
• End to end: a 64 TiB request from a DeviceMemoryResource raises MemoryError, and the pool stays usable.
• test_cuda_utils.py, test_error_handling.py, test_api_docs_consistency.py and test_memory.py pass locally (RTX 5070 Ti, driver 615, CUDA 13.4).

[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.

[coderabbitai]

📝 Summary

Summary by CodeRabbit

• New Features
  • CUDA out-of-memory failures now raise CUDAOutOfMemoryError, which can be caught as either a CUDAError or a standard MemoryError.
  • The exception is available from the top-level cuda.core namespace. Other CUDA errors continue to raise `CUDAError.
• Documentation
  • Updated the error-handling guide, API reference, and release notes with details about the new exception.

The change adds and exports CUDAOutOfMemoryError. Driver and runtime out-of-memory errors now raise this class, which inherits from CUDAError and MemoryError. Tests and documentation cover the new exception.

Changes: CUDA out-of-memory exception

Layer / File(s)	Summary
Exception definition and error classification cuda_core/cuda/core/_utils/cuda_utils.pyi, cuda_core/cuda/core/_utils/cuda_utils.pyx, cuda_core/tests/test_cuda_utils.py	Defines CUDAOutOfMemoryError as a CUDAError and MemoryError subclass. Driver and runtime out-of-memory codes raise it. Tests check its inheritance, error messages, and classification of other errors.
Public API and allocation validation cuda_core/cuda/core/__init__.py, cuda_core/tests/test_memory.py, cuda_core/docs/source/api.rst, cuda_core/docs/source/error_handling.rst, cuda_core/docs/source/release/1.3.0-notes.rst	Exports and documents CUDAOutOfMemoryError. A memory-pool-gated test checks an oversized allocation failure and a subsequent successful allocation.

Assessment against linked issues

Objective	Addressed	Explanation
Add cuda.core.CUDAOutOfMemoryError(CUDAError, MemoryError) and raise it for CUDA_ERROR_OUT_OF_MEMORY and cudaErrorMemoryAllocation [#3260]	✅
Preserve error messages and allow except CUDAError to catch these errors [#3260]	✅
Keep NVRTC out-of-memory errors as NVRTCError [#3260]	✅

Priority: Normal

Change: Bug fix · Severity of issue fixed: Medium

Merge Risk: Low · up to 6b759

The documentation may lead readers to attempt an invalid import. The change is mergeable with a documentation clarification.

Finishing Touches: 💡 1

🛠️ Fix failing CI checks: 💡

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

---

Review info

Run configuration

• Source mode: Auto
• Repository: NVIDIA/cuda-python
• Branch: main
• File: .coderabbit.yaml
• Commit: 590a8bf
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Enterprise
• Run ID: deb66916-c5af-44de-827c-e6ebbf1830a5

Commits

Reviewing files that changed from the base of the PR and between 590a8bf and b7b0f23.

Files selected for processing: 8

• cuda_core/cuda/core/__init__.py
• cuda_core/cuda/core/_utils/cuda_utils.pyi
• cuda_core/cuda/core/_utils/cuda_utils.pyx
• cuda_core/docs/source/api.rst
• cuda_core/docs/source/error_handling.rst
• cuda_core/docs/source/release/1.3.0-notes.rst
• cuda_core/tests/test_cuda_utils.py
• cuda_core/tests/test_memory.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 8 remain after this review.

[coderabbitai]

Minor · Functional Correctness · Quick win

suggestion: Limit the importability claim to these exception classes. The sentence says all cuda.core classes are available at the top level. Classes such as Graph instead live in cuda.core.graph, so a reader following this claim can use an invalid import. Replace “All cuda.core classes” with “These exception classes.” (raw.githubusercontent.com)

[Andy-Jost]

Thanks, the design holds up. CUDAOutOfMemoryError(CUDAError, MemoryError) keeps every existing except CUDAError working, the mapping happens once in the driver and runtime raise paths that HANDLE_RETURN, handle_return, and _check_error all funnel through, cuda.core itself never catches MemoryError, and the end-to-end test asks a capped pool for 64 TiB, so it fails at once without touching real device memory. On the question in #3260: raising a MemoryError subclass for CUDA out-of-memory is fine with me, and it matches what CuPy and RMM users expect.

Before merge:

1. Rebase onto main. Since #3255, _RUNTIME_SUCCESS and _NVRTC_SUCCESS are declared in cuda_utils.pxd and assigned as plain globals in the .pyx, and the check functions are cpdef inline in the .pxd. The only conflict is the constant block in cuda_utils.pyx: keep main's two assignments and add _RUNTIME_OUT_OF_MEMORY beside them. Your exc_type selection merges cleanly into the renamed _raise_driver_error and _raise_runtime_error. No CI has run on this PR yet; after the rebase the workflows are approved and it runs.
2. The release note (and the commit message) say except MemoryError works "as it does in CuPy, PyTorch and NumPy". PyTorch raises torch.OutOfMemoryError, a RuntimeError, as #3260 itself notes; please name CuPy, RMM, and NumPy.
3. error_handling.rst: "All cuda.core classes are importable from the top-level namespace" reads as every class, and graph classes, for one, live in cuda.core.graph. "These exception classes are importable from the top-level cuda.core namespace" says what you mean; please rewrap the paragraph too.

[srimanachanta]

@Andy-Jost I have incorporated your feedback into 6b7591a

[coderabbitai]

Actionable comments posted: 1

---

Review info

Run configuration

• Source mode: Auto
• Repository: NVIDIA/cuda-python
• Branch: main
• File: .coderabbit.yaml
• Commit: d4c71ef
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Enterprise
• Run ID: 2d96acaa-9c23-4910-9e5f-f5beb2bd335b

Commits

Reviewing files that changed from the base of the PR and between b7b0f23 and 6b7591a.

Files selected for processing: 4

• cuda_core/cuda/core/_utils/cuda_utils.pyi
• cuda_core/cuda/core/_utils/cuda_utils.pyx
• cuda_core/docs/source/error_handling.rst
• cuda_core/docs/source/release/1.3.0-notes.rst

Files skipped from review as they are similar to previous changes: 1

• cuda_core/docs/source/release/1.3.0-notes.rst

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 10 remain after this review.

[Andy-Jost]

/ok to test 6b7591a

[github-actions]

Doc Preview CI
🚀 View preview at https://nvidia.github.io/cuda-python/pr-preview/pr-3235/
https://nvidia.github.io/cuda-python/pr-preview/pr-3235/cuda-core/
https://nvidia.github.io/cuda-python/pr-preview/pr-3235/cuda-bindings/
https://nvidia.github.io/cuda-python/pr-preview/pr-3235/cuda-pathfinder/
Preview will be ready when the GitHub Pages deployment is complete.

[Andy-Jost]

Thanks, all three points are addressed: the rebase keeps main's plain _RUNTIME_SUCCESS and _NVRTC_SUCCESS assignments with the new sentinel beside them and the exc_type selection intact on every raise branch, the release note names CuPy, RMM, and NumPy, and the sentence about importable classes is fixed. CI is now running. Approving.

A last wording nit, take it or leave it: "These exception classes are importable from the top-level cuda.core namespace" now follows the MemoryError sentence, so it reads as including the built-in; naming the classes ("CUDAError, NVRTCError, and CUDAOutOfMemoryError are importable ...") avoids that.