voyager-debug

Debug Pipeline or Model

Systematically debug and fix issues with Axelera AI pipelines, models, or inference

Use This Skill When / Not When

• Use when: the user brings an existing error, crash, log, regression, or wrong output.
• Use when: the SDK install is missing, broken, or old, the driver/firmware mismatch, or the Metis board is not detected -- follow references/install-and-board-health.md.
• Not when: debugging is part of building a brand-new pipeline -- route to voyager-launch.
• Not when: they want pure performance measurement of a working pipeline -- route to voyager-bench.
• Process precedence: when a failure is on the table, this skill runs before any domain skill changes code or config.

Instructions

Debug the specified issue: $ARGUMENTS

{{INCLUDE common/voyager-sdk-setup.md}}

{{INCLUDE common/voyager-task-integration.md}}

Step 1: Issue Classification

Identify the type of issue:

• Deployment Error: Model fails to compile/deploy
• Runtime Error: Inference fails or crashes
• Accuracy Issue: Model produces incorrect results
• Performance Issue: Low throughput or high latency
• Display Issue: Visualization problems

Step 2: Environment Diagnostics

Run initial diagnostics. Only probe hardware directly when .voyager-runtime.json says execution.mode is execute_on_device.

# Check environment
echo "AXELERA_FRAMEWORK: $AXELERA_FRAMEWORK"
echo "AXELERA_RUNTIME_DIR: $AXELERA_RUNTIME_DIR"
echo "PYTHONPATH: $PYTHONPATH"

# Check hardware on a Voyager SDK host
axdevice

# Check Python environment
python --version
pip list | grep axelera

# Version evidence for install/driver/firmware problems
axversion            # SDK version
axversion --driver   # driver version
axdevice -v          # firmware + board controller

If the problem is the environment itself (SDK missing or old, driver or firmware mismatch, board not detected, ENOTTY/AXL_IOCTL errors), follow references/install-and-board-health.md: it carries the fresh-install commands, the v1.7.0 compatibility matrix, the upgrade path including the post-upgrade driver/model-recompile trap, and the board-not-detected ladder. Firmware flashing, device reboots, and system package installs always need explicit user confirmation first.