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
-
Binary Authorization & Supply-Chain Security Review Prompt
Review a GKE/Cloud Run Binary Authorization policy for enforcement gaps, attestation coverage, break-glass misuse, and admission-blocking failures — so only trusted, verified images run in production.
-
GKE Gateway API & Ingress Config Review Prompt
Review GKE Gateway API and Ingress configuration for routing gaps, unhealthy backends, missing health checks, TLS/cert issues, and misapplied HTTPRoute rules before external traffic hits a 404 or 502.
-
GKE Autoscaling: Cluster Autoscaler & HPA Debug Prompt
Diagnose GKE scaling failures — pods stuck Pending while nodes don't scale up, HPA that won't add replicas, and node pools that scale down too aggressively or not at all.
-
GKE Cluster Upgrade Strategy & Release Channel Prompt
Plan a safe GKE control-plane and node upgrade — release channels, maintenance windows, surge settings, and workload disruption budgets — so version bumps don't break APIs or evict critical pods.
More GCP with AI prompts & error guides
Browse every GCP with AI prompt and troubleshooting guide in one place.
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.