Troubleshooting

This guide helps you diagnose and resolve common issues when installing, building engines with, and running inference using TensorRT-RTX on RTX GPUs. It points to the most relevant documentation for platform support, deployment, and debugging workflows.

What You Will Learn

• Installation and environment issues: GPU, driver, CUDA, and SDK setup problems on supported platforms

• Build and engine issues: AOT/JIT compilation failures, engine compatibility, and porting from TensorRT

• Inference and runtime issues: Execution errors, dynamic shapes, and reproducing failures with capture and replay

How to Use This Guide

1. Confirm platform support: Verify your GPU, OS, and dependency versions against the Support Matrix and Prerequisites before changing application code.

2. Match the workflow phase: Use the installation, build, or inference sections below depending on where the failure occurs.

3. Reproduce build failures: On Linux, use API Capture and Replay to record and replay engine-building API sequences without the original application or model source.

4. Gather diagnostics: Capture TensorRT-RTX version, GPU model, driver and CUDA versions, and relevant log output before reporting an issue.

Getting Additional Help

If this guide does not resolve your issue:

• Post questions on the NVIDIA Developer TensorRT-RTX forum

• Open an issue on the TensorRT-RTX GitHub repository

• Review Release Notes for known issues and fixes in your version

Installation Issues

Symptoms such as missing libraries, loader errors, or the SDK failing to detect a GPU often trace to environment setup rather than application logic.

Table 26 Installation symptoms

Symptom	Phase	Next step
Missing libraries, loader errors, or the SDK does not detect a GPU	Install	Confirm that your RTX GPU, OS, driver, and CUDA toolkit versions are in scope. Refer to Support Matrix and Prerequisites.
First-time or broken install	Install	Follow the platform-specific steps for the SDK zip (Windows) or tarball (Linux), including PATH and library path configuration. Refer to Installing TensorRT-RTX and Installation Guide Overview.
import tensorrt_rtx fails	Install	Verify that the wheel or bindings match your Python version and that dependent CUDA libraries are on the library path. Refer to Prerequisites for dependency versions.

Build and Engine Issues

Engine build failures occur during ahead-of-time (AOT) compilation on the build machine or during just-in-time (JIT) compilation when the engine is first loaded on the end-user GPU.

Table 27 Build and engine symptoms

Symptom	Phase	Next step
Unsupported ONNX operators or graph features	Build	Compare the model against the operator catalog and export guidance. Update unsupported ops or deprecated network modes before build. Refer to Operators, ONNX Conversion Guide, and Porting Guide for TensorRT Applications.
TensorRT engine does not load in TensorRT-RTX	Build	Serialized TensorRT engines cannot be loaded by TensorRT-RTX. Rebuild with TensorRT-RTX and update library and Python module names. Refer to Porting Guide for TensorRT Applications.
Engine fails across GPUs or releases	Build	Use CPU-only AOT defaults, Turing-specific engines where needed, and IRuntime::getEngineValidity() before deployment. Refer to CPU-Only AOT and TensorRT-RTX Engines and Version Compatibility.
Need to reproduce a build-time failure (Linux)	Build	Record API calls during the build phase and replay them with tensorrt_player. Refer to TensorRT-RTX API Capture and Replay.

Inference and Runtime Issues

Failures during engine deserialization, JIT compilation, or execution often relate to engine validity, tensor shapes, or concurrent GPU use.

Table 28 Inference and runtime symptoms

Symptom	Phase	Next step
Engine fails to load or JIT compile on the target machine	Inference	Verify GPU support, driver version, and that the engine was built for the installed TensorRT-RTX release. Refer to Support Matrix, Release Notes, and CPU-Only AOT and TensorRT-RTX Engines.
Shape, precision, or accuracy errors at runtime	Inference	Dynamic input dimensions, quantized types, and strongly typed networks have specific API and ONNX requirements. Refer to Working with Dynamic Shapes, Working with Quantized Types, and Advanced Topics.
Latency issues or concurrent graphics workloads	Inference	Refer to Best Practices and Simultaneous Compute and Graphics.
Behavior differs between machines	Inference	Capture the build-phase API trace where the issue reproduces and replay on another host. Refer to TensorRT-RTX API Capture and Replay.