Aoti Debug

When you're wrestling with AOTInductor segfaults or device mismatch errors, this skill walks you through the debugging process systematically. It covers the critical first check (compile device must match load device, input shapes and devices must align), then routes you through common failure modes like CUDA illegal memory access and Triton index issues. The environment variable reference table is legitimately useful. You get concrete flags like AOTI_RUNTIME_CHECK_INPUTS and PYTORCH_NO_CUDA_MEMORY_CACHING with clear explanations of when they take effect. This is the kind of reference you want open in a terminal while debugging a production AOTI crash at 2am, not general advice about compilation.

skills.sh installs: 3.1K
GitHub stars: 105.3K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add pytorch/pytorch --skill aoti-debug --agent claude-code

Installs into .claude/skills of the current project.

Files

AOTI Debugging Guide

This skill helps diagnose and fix common AOTInductor issues.

Error Pattern Routing

Check the error message and route to the appropriate sub-guide:

Triton Index Out of Bounds

If the error matches this pattern:

Assertion `index out of bounds: 0 <= tmpN < ksM` failed

→ Follow the guide in triton-index-out-of-bounds.md

All Other Errors

Continue with the sections below.

First Step: Always Check Device and Shape Matching

For ANY AOTI error (segfault, exception, crash, wrong output), ALWAYS check these first:

Compile device == Load device: The model must be loaded on the same device type it was compiled on
Input devices match: Runtime inputs must be on the same device as the compiled model
Input shapes match: Runtime input shapes must match the shapes used during compilation (or satisfy dynamic shape constraints)

# During compilation - note the device and shapes
model = MyModel().eval()           # What device? CPU or .cuda()?
inp = torch.randn(2, 10)           # What device? What shape?
compiled_so = torch._inductor.aot_compile(model, (inp,))

SKILL.md on GitHub