debugging dags

DevOps Community

Skill notes

Running the CLI

Run all af commands using uvx (no installation required): Throughout this document, af is shorthand for uvx --from astro-airflow-mcp af.

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 If no DAG was specified: Run af health to find recent failures across all DAGs

Step 2: Get the Error Details

Once you have identified a failed task: Get task logs using af tasks logs <dag_id> <dag_run_id> <task_id> Look for the actual exception - scroll past the Airflow boilerplate to find the real error Categorize the failure type: Data issue: Missing data, schema change, null values, constraint violation

Step 3: Check Context

Gather additional context to understand WHY this happened: Recent changes: Was there a code deploy? Check git history if available Data volume: Did data volume spike? Run a quick count on source tables Upstream health: Did upstream tasks succeed but produce unexpected data? Historical pattern: Is this a recurring failure? Check if same task failed before

On Astro

If you're running on Astro, these additional tools can help with diagnosis: Deployment activity log: Check the Astro UI for recent deploys — a failed deploy or recent code change is often the cause of sudden failures Astro alerts: Configure alerts in the Astro UI for proactive failure monitoring (DAG failure, task duration, SLA miss) Observability: Use the Astro observability dashboard to track DAG health trends and spot recurring issues

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
DevOps
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@diegosouzapw · no license declared
Token usage
Lean
Setup complexity
Plug-and-play
External API key
Not required
Operating systems
Windows
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Output preview debugging-dags.preview
# Step 4: Provide Actionable Output

Structure your diagnosis as:

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.