/error-handling

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: LicenseRef-NvidiaProprietary
#
# NVIDIA CORPORATION, its affiliates and licensors retain all intellectual
# property and proprietary rights in and to this material, related
# documentation and any modifications thereto. Any use, reproduction,
# disclosure or distribution of this material and related documentation
# without an express license agreement from NVIDIA CORPORATION or
# its affiliates is strictly prohibited.
name: error-handling
description: >
  Error checking patterns for both C and Python. Use when user asks about error
  handling, checking errors, debugging ovrtx failures, or troubleshooting.
license: LicenseRef-NvidiaProprietary
author: NVIDIA ovrtx
tags:
  - ovrtx
  - errors
  - debugging
tools:
  - Read
  - Grep

Error Handling

When to Use

Use this skill when the user asks about error handling, checking errors, debugging ovrtx failures, or troubleshooting.

Inputs

Resolve inputs in this order: existing repository files and referenced snippets, explicit user request, then broader agent context.

• Target API surface: Python, C/C++, or both.
• Language and failure point: Python sync call, Python async wait/fetch, C enqueue, C wait, C fetch, or C map/unmap.
• Error signal available to the caller: exception text, `ovrtx_status_t`, operation index, result handle, or `ovrtx_get_last_error()`.
• Operation being debugged and whether the caller needs recovery, logging, or propagation guidance.
• Repository source snippets referenced below. Treat these snippets as the API source of truth.

Prerequisites

• Use an ovrtx checkout that contains the referenced examples and docs tests.
• Read the relevant `> **Source:**` snippet before writing or explaining API usage.
• Determine where errors surface for the operation before adding checks; enqueue success does not guarantee async completion success.

Instructions

1. Identify whether the failure path is Python synchronous, Python async, C enqueue, C wait, C fetch, or C map/unmap. 2. In Python, catch `RuntimeError` around the API call or around `wait()` for async operations, depending on where the operation surfaces errors. 3. In C, check every returned `ovrtx_result_t.status` or enqueue status before using output values. 4. After C wait calls, inspect operation errors before fetching results, and call `ovrtx_get_last_error()` immediately when a status indicates failure. 5. When changing code, run the narrow example or docs test that exercises the failing operation whenever practical.

Output Format

• For explanations, cite the relevant API names, source snippets, and caveats.
• For code changes, summarize the files changed, snippets affected, and validation run.

Scripts

This skill has no scripts.

Limitations

• The referenced snippets remain the source of truth; update or add tested snippets before documenting new API usage.

Overview

In Python, ovrtx raises `RuntimeError` with descriptive messages on failure. In C, every API call returns a status code that must be checked, and error details are retrieved with `ovrtx_get_last_error()`.

Python

Automatic error handling

All Python API methods raise `RuntimeError` on failure. The minimal step example shows the synchronous call shape to wrap in user code:

> **Source:** `tests/docs/python/test_error_handling.py` snippet `doc-python-sync-runtime-error` > > The test demonstrates the synchronous Python error surface pattern.

Async operation errors

Errors from async operations surface when you call `wait()`:

> **Source:** `tests/docs/python/test_error_handling.py` snippet `doc-python-async-operation-error`

Step errors

> **Source:** `examples/python/minimal/main.py` snippet `step` > > Wrap in `try/except RuntimeError` to handle step failures.

C

Check every return value

> **Source:** `examples/c/minimal/main.cpp` snippet `create-renderer` > > **Source (continued):** `examples/c/minimal/main.cpp` snippet `load-usd-and-wait` > > Every API call returns a status code. Check with the `check-error-helper` snippet pattern.

check_and_print_error helper function

From the minimal C example -- a template helper that checks the status, prints to `std::cerr`, and returns whether an error occurred. Works with both `ovrtx_result_t` and `ovrtx_enqueue_result_t`:

> **Source:** `examples/c/minimal/main.cpp` snippet `check-error-helper`

Per-operation errors from wait

Asynchronous errors (e.g., file not found during USD load) are reported through `ovrtx_wait_op`:

> **Source:** `examples/c/minimal/main.cpp` snippet `load-usd-and-wait` > > Check `wait_result.num_error_ops` and iterate `wait_result.error_op_ids` after `ovrtx_wait_op`.

Log callback (C)

Set a process-global callback to receive log messages, with severity filtering and per-channel rules:

> **Source:** `tests/docs/c/test_logging.cpp` snippet `doc-log-callback-prefix-filter-c`

Log severity levels follow carb's numeric ordering: `OVX_LOG_VERBOSE` (-2), `OVX_LOG_INFO` (-1), `OVX_LOG_WARNING` (0), `OVX_LOG_ERROR` (1), `OVX_LOG_FATAL` (2). The callback is process-global: its lifetime is `ovrtx_initialize` to `ovrtx_shutdown`, so it observes messages emitted before the first renderer is created and after the last one is destroyed (e.g. plugin-load and asset-eviction messages). The callback may be invoked from any thread. Message strings are only valid during the callback. Note that if multiple OV libraries are used in an app, multiple logging callbacks may be registered, one from each OV library. In this case, it is the host app's responsibility to ensure that the callback's access to the host app's logging system is thread-safe.

channel_filter syntax

`channel_filter` is a comma-separated list of `<channel_prefix>=<level>` entries (RUST_LOG-style). The channel prefix is matched against carb's dotted source name; longest matching prefi