debug-cuda-crash

Log FlashInfer API inputs to diagnose CUDA crashes.

2|1|Updated Oct 21, 2025
One-click install
npx skills add https://github.com/fw-ai/flashinfer --skill debug-cuda-crash-fw-ai
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: debug-cuda-crash
Source: https://github.com/fw-ai/flashinfer/tree/main/.claude/skills/debug-cuda-crash
Command: npx skills add https://github.com/fw-ai/flashinfer --skill debug-cuda-crash-fw-ai

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps you diagnose and fix CUDA crashes in your FlashInfer applications by providing detailed logging of API inputs before errors occur.

Core Features & Use Cases

  • Capture Pre-Crash Data: Logs tensor shapes, dtypes, and values before a CUDA error halts execution.
  • Identify Root Cause: Pinpoints the exact data or configuration that triggers crashes like illegal memory access, NaNs, or OOM errors.
  • Use Case: When your model training crashes with a CUDA error, use this Skill to enable logging, reproduce the crash, and examine the logged inputs to find the problematic tensor shape or value.

Quick Start

Enable detailed API logging to a file named debug.log by running export FLASHINFER_LOGLEVEL=3 and export FLASHINFER_LOGDEST=debug.log before executing your Python script.

Frequently Asked Questions about debug-cuda-crash

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

FAQPage Schema
How do I debug a CUDA crash caused by illegal memory access in FlashInfer?

You can debug illegal memory access in FlashInfer by enabling API logging to capture tensor shapes, dtypes, and values before the crash. Set FLASHINFER_LOGLEVEL=3 and FLASHINFER_LOGDEST=debug.log, reproduce the crash, and examine the logged inputs to pinpoint the problematic tensor configuration.

Why does my FlashInfer model training crash with NaN or Inf values during execution?

FlashInfer model training crashes with NaN or Inf values due to invalid tensor inputs or incorrect data types. Enabling API logging captures tensor statistics before the error, allowing you to identify the exact data or configuration that triggers the invalid numerical values during execution.

What is the best way to capture tensor inputs before a CUDA out-of-memory error occurs?

The best way to capture tensor inputs before a CUDA out-of-memory error is enabling API logging in FlashInfer. By setting FLASHINFER_LOGLEVEL=3, the system records tensor shapes and values continuously, ensuring pre-crash data is available for diagnosis when the OOM error halts execution.

Can I use compute-sanitizer and cuda-gdb for advanced CUDA debugging alongside API logging?

Yes, FlashInfer supports advanced debugging using compute-sanitizer and cuda-gdb alongside API logging. These tools enable deeper kernel-level inspection through printf statements and multi-process logging to diagnose complex CUDA crashes beyond standard tensor input analysis.

Does FlashInfer API logging support multi-process environments for diagnosing CUDA crashes?

Yes, FlashInfer API logging supports multi-process environments for diagnosing CUDA crashes. Advanced debugging techniques include multi-process logging, allowing you to track tensor inputs and identify root causes like incorrect data types or illegal memory access across distributed training workflows.

What are the limitations of using API logging to debug CUDA crashes?

API logging for debugging CUDA crashes is limited to capturing tensor shapes, dtypes, and values before the error occurs. While it identifies root causes like illegal memory access or OOM, complex kernel-level issues may require additional tools like compute-sanitizer or cuda-gdb for full diagnosis.