Tripy Debugging

Debugging and Error Reporting in nvtripy

When to Use

• Interpreting TripyException error messages and stack traces
• Enabling debug output for MLIR or TensorRT compilation
• Understanding the stack info system for precise error locations
• Adding error handling to new ops or modules
• Diagnosing compilation or runtime failures

Error Reporting System

raise_error — The Primary Error Function

From nvtripy/common/exception.py:

from nvtripy.common.exception import raise_error

raise_error(
    "Brief description of the error.",
    details=[
        "Additional context line 1.",
        "Additional context line 2.",
        some_tensor,  # Will include the tensor's creation stack info
    ],
)

• First argument: The main error message (string)
• details: A list of strings and/or tensors. Tensors will have their stack info rendered.
• Raises TripyException

Stack Info System

Every tensor captures its creation stack trace (_stack_info) for precise error reporting. This is managed in nvtripy/utils/stack_info.py.

When a tensor appears in raise_error details, the system renders the exact line and column where the tensor was created, helping users trace back to the problematic code.

Key points:

• Tensor.from_trace_tensor(out, include_code_index=stack_depth) — sets the stack depth for error reporting
• STACK_DEPTH_OF_FROM_TRACE_TENSOR = 4 — the default depth in create_op
• stack_depth_offset parameter in create_op adjusts for wrapper functions

Exception Hierarchy

TripyException (main user-facing exception)
└── Raised by raise_error() with formatted stack info

Debug Configuration

Environment Variables

Set these before running to enable debug output:

| Variable | Default | Description |

|----------|---------|-------------|

| TRIPY_MLIR_DEBUG_ENABLED | "0" | Enable MLIR debug output |

| TRIPY_MLIR_DEBUG_TYPES | "-translate-to-tensorrt" | Comma-separated MLIR pass types to debug |

| TRIPY_MLIR_DEBUG_PATH | "/tripy/mlir-dumps" | Directory for MLIR debug dumps |

| TRIPY_TRT_DEBUG_ENABLED | "0" | Enable TensorRT debug output |

| TRIPY_TRT_DEBUG_PATH | "/tripy/tensorrt-dumps" | Directory for TensorRT debug dumps |

| TRIPY_EXTRA_ERROR_INFORMATION | "" | Comma-separated extra error info |

Runtime Configuration

From nvtripy/config.py:

import nvtripy as tp

# Timing cache (speeds up repeated compilations)
tp.config.timing_cache_file_path  # Default: /tmp/tripy-cache

# Input validation (disable for performance in production)
tp.config.enable_input_validation = False

# Extra error information
tp.config.extra_error_information = ["detailed"]

Test Helper for Config Changes

from tests import helper

with helper.config("enable_input_validation", False):
    # Code runs with validation disabled
    ...
# Automatically restored after the block

Logging System

The logging system (nvtripy/logging/) provides granular control:

import nvtripy as tp

# The global logger
logger = tp.logger

# Set verbosity for specific modules
logger.verbosity_trie.set("nvtripy.backend", "verbose")

The VerbosityTrie allows setting different log levels for different module paths, using a trie data structure for efficient prefix matching.

Diagnosing Common Issues

Constraint Validation Errors

Error pattern: Expected 'input' to be one of [...] (but it was '...')

This comes from the constraint system. Check:

• The input_requirements in the @wrappers.interface decorator
• The actual dtypes of the inputs being passed
• Whether auto-casting should handle this case

Compilation Errors

Enable MLIR debug output:

TRIPY_MLIR_DEBUG_ENABLED=1 python my_script.py

Check the dumps in /tripy/mlir-dumps/ for the MLIR IR at each pass.

Shape Mismatch Errors

The trace system tracks shapes through infer_rank on trace ops. Check:

• The infer_rank policy on the trace op
• Whether broadcasting is handled correctly
• Dynamic dimensions (DYNAMIC_DIM = -1) vs static shapes

Runtime Errors from Compiled Functions

Enable TensorRT debug output:

TRIPY_TRT_DEBUG_ENABLED=1 python my_script.py

Check:

• Input shapes fall within the InputInfo bounds
• Dynamic shapes are correctly configured with min/opt/max

Adding Error Handling to New Code

In Frontend Ops

def my_op(input, dim):
    if input.rank < 2:
        raise_error(
            f"Input must have rank >= 2, but got rank: {input.rank}",
            details=[
                "Input is expected to have shape (N, *) where N is the batch size.",
                input,  # This renders the tensor's creation location
            ],
        )

In Modules

def forward(self, x):
    if self.quant_dtype is not None and self.weight_quant_dim == 1:
        raise_error(
            "Unsupported quantization parameters.",
            [
                "weight_quant_dim cannot be 1 when input_scale is provided.",
                f"input_scale={self.input_scale}, weight_quant_dim={self.weight_quant_dim}",
            ],
        )

Testing Errors

Use the helper.raises context manager:

from tests import helper
import nvtripy as tp

def test_invalid_dtype_fails():
    a = tp.Tensor([1.0, 2.0])
    b = tp.ones((2,), dtype=tp.float16)
    with helper.raises(tp.TripyException, match="Expected.*one of"):
        c = a + b

The raises helper supports:

• ExcType: Expected exception type
• match: Regex pattern to match against error message
• has_stack_info_for: Verify that specific tensors' stack info appears in the error

Checklist

• [ ] Use raise_error() instead of raw raise for user-facing errors
• [ ] Include relevant tensors in details for stack info rendering
• [ ] Error message is actionable (says what went wrong AND what to do)
• [ ] Test error cases with helper.raises(tp.TripyException, match=...)
• [ ] Debug env vars documented if adding new debug output