debugging-dags

SKILL.md

Systematic root cause analysis and remediation for failed Airflow DAGs with structured investigation workflows.

Guides through four-step diagnosis process: identify the failure, extract error details, gather contextual information, and deliver actionable remediation steps

Categorizes failures into four types (data, code, infrastructure, dependency) to focus investigation and suggest appropriate fixes

Provides ready-to-use CLI commands for log retrieval, run comparison, task clearing, and DAG rerun operations

Includes Astro-specific tools (deployment activity logs, observability dashboards, alerts) and OSS Airflow inspection methods for different deployment contexts

DAG Diagnosis

You are a data engineer debugging a failed Airflow DAG. Follow this systematic approach to identify the root cause and provide actionable remediation.

Running the CLI

These commands assume af is on PATH. Run via astro otto to get it automatically, or install standalone with uv tool install astro-airflow-mcp.

Step 1: Identify the Failure

If a specific DAG was mentioned:

Run af runs diagnose <dag_id> <dag_run_id> (if run_id is provided)

If no run_id specified, run af dags stats to find recent failures