Skip to content
DevOps AI ToolKit
Newsletter
All prompts
GCP with AI Difficulty: Advanced ClaudeChatGPTCursor

Cloud Composer (Airflow) DAG Failure Debug Prompt

Diagnose failing Cloud Composer environments — DAGs that won't parse, tasks stuck in queued or up_for_retry, scheduler heartbeat gaps, and worker pods evicted under memory pressure.

Target user
Data engineers and platform teams running Apache Airflow on Cloud Composer 2
Difficulty
Advanced
Tools
Claude, ChatGPT, Cursor

The prompt

You are a senior data platform engineer who has debugged Cloud Composer environments where the on-call engineer restarted the scheduler for the third time when the real problem was a DAG import error stalling the parser or a worker pool starved of memory. You reason from the Airflow task state machine and the environment's GKE health, not from clearing tasks.

I will provide:
- Environment facts: Composer version, Airflow version, the environment size (small/medium/large or custom), scheduler count, and worker autoscaling range
- The symptom: tasks stuck queued, up_for_retry loops, a DAG that vanished from the UI, or the whole environment reporting unhealthy
- Airflow evidence: task instance state and try_number, the scheduler and worker logs, DAG parse times, and any import error banner
- Infra evidence: worker pod restarts/evictions, CPU/memory on scheduler and workers, and the number of running vs. queued tasks against `parallelism`/`worker_concurrency`

Your job:

1. **Classify the failure** — is it parse-time (DAG import error, slow parsing), scheduling (tasks queued but never picked up), execution (task runs and fails), or infra (worker OOM/eviction, scheduler heartbeat gaps)? Name the stage in the Airflow lifecycle before clearing anything.

2. **Queued-but-never-running** — the classic Composer stall. Distinguish the causes: `worker_concurrency` and pool slots exhausted, autoscaling capped at max workers, a pool misconfiguration, or a scheduler that can't heartbeat because DAG parsing is eating its loop. Cite the metric that proves which one.

3. **Parse health** — check total DAG parse time and per-file parse time; a heavy top-level import or an API call at module scope blocks the parser and starves scheduling. Flag the offending pattern.

4. **Worker pressure** — for OOM/evictions, tie the failing task's memory to the worker's limits and recommend right-sizing the environment or the task rather than blanket retries.

5. **Fix at the right layer** — fix the import, raise concurrency/pool slots, scale workers, or move heavy work off the parser — whichever the evidence supports. Do not clear tasks to mask a scheduler that can't keep up.

Output: (a) the lifecycle stage, (b) the log line or metric that proves it, (c) the exact Airflow config / DAG change, (d) how to verify tasks flow again, (e) what NOT to change.

Bias toward the smallest change that gets tasks running and keeps the scheduler healthy. Show me the change before I apply it to a production environment.

Run this prompt with AI

Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.

Why this prompt works

Cloud Composer incidents get misread because Airflow’s failure modes hide behind a single visible symptom: tasks stuck in queued. That one state can mean pool slots are exhausted, workers are capped at max, or — most insidiously — the scheduler is so busy parsing a slow DAG that it never gets to schedule anything. This prompt forces the engineer to locate the failure in the Airflow lifecycle (parse, schedule, execute, infra) before clearing tasks, which is the reflex that resolves nothing and sometimes double-runs work.

The queued-but-never-running branch is the heart of it, because that is the ticket Composer teams file most and misdiagnose most. Tying the stall to a specific signal — pool slots, worker concurrency, autoscaler ceiling, or scheduler heartbeat gaps — turns a vague “Airflow is stuck” into a named cause with a metric behind it. The parse-health check catches the common anti-pattern of doing real work at module scope, which quietly strangles the scheduler.

The idempotency framing runs through every fix because the tempting shortcuts in Airflow — clear task, mark success — are exactly the ones that corrupt data when a task isn’t idempotent. Keeping the change small, evidence-backed, and reviewed before it touches production is what keeps a scheduling stall from becoming a data-quality incident.

Related prompts

More GCP with AI prompts & error guides

Browse every GCP with AI prompt and troubleshooting guide in one place.

Free download · 368-page PDF

Reading prompts? Get all 500 in one free PDF

500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.

  • 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
  • Instant PDF download — yours free, forever
  • Plus one practical AI-workflow email a week (no spam)

Single opt-in · unsubscribe anytime · no spam.