skills.rest
pytorch
pytorchOFFICIAL
Explore all skills by this author →
WebsiteGitHub

pt2-bug-basher

Debug PyTorch 2 compiler stack failures across Dynamo, Inductor, and AOTAutograd.

103k|29.1k|Updated Aug 13, 2016
Search Tags:#Debugging#torch.compile#inductor#pyTorch#Triton#Dynamo#aotautograd
One-click install
npx skills add https://github.com/pytorch/pytorch --skill pt2-bug-basher
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: pt2-bug-basher
Source: https://github.com/pytorch/pytorch/tree/main/.claude/skills/pt2-bug-basher
Command: npx skills add https://github.com/pytorch/pytorch --skill pt2-bug-basher

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Debugging failures in the PyTorch 2 compiler stack (Dynamo, Inductor, AOTAutograd, FX graphs) is complex because errors span trace-time vs runtime, multiple compilation modes, and various backend stages. This Skill provides a structured workflow to reproduce, minimize, classify, and fix these bugs.

Core Features & Use Cases

  • Error Triage: Classifies failures into categories (graph breaks, BackendCompilerFailed, recompilation, accuracy, InternalTorchDynamoError, runtime crashes, Triton failures) and routes to the right diagnostic approach.
  • Diagnostic Tools: Uses TORCH_LOGS, TORCH_COMPILE_DEBUG, TORCHDYNAMO_REPRO_AFTER, and the minifier to isolate minimal reproductions.
  • Test-First Workflow: Adds a failing unit test before root-cause investigation, validates it fails on main, then applies and verifies the fix.
  • Use Case: When a user hits a BackendCompilerFailed exception from torch.compile, this Skill walks through reproducing the failure, running the AOT minifier, inspecting FX graphs, identifying the offending op, and writing a regression test.

Quick Start

Use the pt2-bug-basher skill to debug the torch.compile BackendCompilerFailed error in my script and add a regression test.

Frequently Asked Questions about pt2-bug-basher

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a torch.compile BackendCompilerFailed error?▼

Run TORCHDYNAMO_REPRO_AFTER=aot TORCHDYNAMO_REPRO_LEVEL=2 to generate a minifier_launcher.py, then execute python minifier_launcher.py minify to isolate the minimal failing graph. Inspect the FX graph with TORCH_COMPILE_DEBUG=1 to identify the offending op.

Why does torch.compile keep recompiling my model?▼

Excessive recompilation happens when guards are too specific, often due to changing tensor shapes without mark_dynamic(), Python scalar values that vary between calls, or global state mutations. Check TORCH_LOGS=recompiles,recompiles_verbose,guards to identify the failing guard.

How to find graph breaks in a compiled PyTorch model?▼

Run TORCH_LOGS=graph_breaks python your_script.py to log every graph break with its reason. The unsupported operation message identifies the cause, typically data-dependent control flow, in-place ops on inputs, or non-traceable function calls.

What causes accuracy mismatches between compiled and eager PyTorch models?▼

Compiled models can diverge from eager due to reduction order changes in fused kernels, dtype promotions, or numerical precision differences. Use TORCHDYNAMO_REPRO_LEVEL=4 with same_two_models() and cast_to_fp64() to binary search the diverging operation.

How do I debug CUDA illegal memory access errors in compiled PyTorch code?▼

Make the crash deterministic with PYTORCH_NO_CUDA_MEMORY_CACHING=1 CUDA_LAUNCH_BLOCKING=1, then enable TORCHINDUCTOR_NAN_ASSERTS=1 to find the first kernel producing bad values. Dynamic shape issues are a historically common source of IMA in compiled graphs.

Related Skills

Explore More Software Engineering Skills→
Fudan-SMI-labFudan-SMI-lab
39

torch-npu-venv-setup-cpu-base

Pin CPU-base PyTorch and install matching torch-npu and torchvision.

Official
Intermediate
TalonT-OrgTalonT-Org
5

resolve-review

Fetch GitHub PR review comments, apply fixes, commit each, and run tests.

Official
Advanced
TorchedHatTorchedHat
6

compile-trace-inductor

Diagnose PyTorch Inductor compilation and performance issues by tracing IR transformations.

Official
Advanced
TorchedHatTorchedHat
6

compile-trace-dynamo

Diagnose PyTorch Dynamo compilation failures via FX graph inspection.

Official
Intermediate