troubleshooting-astro-deployments
Troubleshoot Astronomer production deployments with Astro CLI. Use when investigating deployment issues, viewing production logs, analyzing failures, or managing deployment environment variables.
- Installs
- 628
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/astronomer/agents --skill troubleshooting-astro-deployments- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads troubleshooting-astro-deployments automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Astro Deployment Troubleshooting
This skill helps you diagnose and troubleshoot production Astronomer deployments using the Astro CLI.
For deployment management, see the managing-astro-deployments skill. For local development, see the managing-astro-local-env skill.
Quick Health Check
Start with these commands to get an overview:
# 1. List deployments to find target
astro deployment list
# 2. Get deployment overview
astro deployment inspect <DEPLOYMENT_ID>
# 3. Check for errors
astro deployment logs <DEPLOYMENT_ID> --error -c 50
Viewing Deployment Logs
Use -c to control log count (default: 500). Log flags cannot be combined — use one component or level flag per command.
Component-Specific Logs
View logs from specific Airflow components:
# Scheduler logs (DAG processing, task scheduling)
astro deployment logs <DEPLOYMENT_ID> --scheduler -c 50
# Worker logs (task execution)
astro deployment logs <DEPLOYMENT_ID> --workers -c 30
# Webserver logs (UI access, health checks)
astro deployment logs <DEPLOYMENT_ID> --webserver -c 30
# Triggerer logs (deferrable operators)
astro deployment logs <DEPLOYMENT_ID> --triggerer -c 30
Log Level Filtering
Filter by severity:
# Error logs only (most useful for troubleshooting)
astro deployment logs <DEPLOYMENT_ID> --error -c 30
# Warning logs
astro deployment logs <DEPLOYMENT_ID> --warn -c 50
# Info-level logs
astro deployment logs <DEPLOYMENT_ID> --info -c 50
Search Logs
Search for specific keywords:
# Search for specific error
astro deployment logs <DEPLOYMENT_ID> --keyword "ConnectionError"
# Search for specific DAG
astro deployment logs <DEPLOYMENT_ID> --keyword "my_dag_name" -c 100
# Find import errors
astro deployment logs <DEPLOYMENT_ID> --error --keyword "ImportError"
# Find task failures
astro deployment logs <DEPLOYMENT_ID> --error --keyword "Task failed"
Complete Investigation Workflow
Step 1: Identify the Problem
# List deployments with status
astro deployment list
# Get deployment details
astro deployment inspect <DEPLOYMENT_ID>
Look for:
- Status: HEALTHY vs UNHEALTHY
- Runtime version compatibility
- Resource limits (CPU, memory)
- Recent deployment timestamp
Step 2: Check Error Logs
# Start with errors
astro deployment logs <DEPLOYMENT_ID> --error -c 50
Look for:
- Recurring error patterns
- Specific DAGs failing repeatedly
- Import errors or syntax errors
- Connection or credential errors
Step 3: Review Scheduler Logs
# Check DAG processing
astro deployment logs <DEPLOYMENT_ID> --scheduler -c 30
Look for:
- DAG parse errors
- Scheduling delays
- Task queueing issues
Step 4: Check Worker Logs
# Check task execution
astro deployment logs <DEPLOYMENT_ID> --workers -c 30
Look for:
- Task execution failures
- Resource exhaustion
- Timeout errors
Step 5: Verify Configuration
# Check environment variables
astro deployment variable list --deployment-id <DEPLOYMENT_ID>
# Verify deployment settings
astro deployment inspect <DEPLOYMENT_ID>
Look for:
- Missing or incorrect environment variables
- Secrets configuration (AIRFLOW__SECRETS__BACKEND)
- Connection configuration
Common Investigation Patterns
Recurring DAG Failures
Follow the complete investigation workflow above, then narrow to the specific DAG:
astro deployment logs <DEPLOYMENT_ID> --keyword "my_dag_name" -c 100
Resource Issues
# 1. Check deployment resource allocation
astro deployment inspect <DEPLOYMENT_ID>
# Look for: resource_quota_cpu, resource_quota_memory
# Worker queue: max_worker_count, worker_type
# 2. Check for worker scaling issues
astro deployment logs <DEPLOYMENT_ID> --workers -c 50
# 3. Look for out-of-memory errors
astro deployment logs <DEPLOYMENT_ID> --error --keyword "memory"
Configuration Problems
# 1. Review environment variables
astro deployment variable list --deployment-id <DEPLOYMENT_ID>
# 2. Check for secrets backend configuration
# Look for: AIRFLOW__SECRETS__BACKEND, AIRFLOW__SECRETS__BACKEND_KWARGS
# 3. Verify deployment settings
astro deployment inspect <DEPLOYMENT_ID>
# 4. Check webserver logs for auth issues
astro deployment logs <DEPLOYMENT_ID> --webserver -c 30
Import Errors
# 1. Find import errors
astro deployment logs <DEPLOYMENT_ID> --error --keyword "ImportError"
# 2. Check scheduler for parse failures
astro deployment logs <DEPLOYMENT_ID> --scheduler --keyword "Failed to import" -c 50
# 3. Verify dependencies were deployed
astro deployment inspect <DEPLOYMENT_ID>
# Check: current_tag, last deployment timestamp
Environment Variables Management
List Variables
# List all variables for deployment
astro deployment variable list --deployment-id <DEPLOYMENT_ID>
# Find specific variable
astro deployment variable list --deployment-id <DEPLOYMENT_ID> --key AWS_REGION
# Export variables to file
astro deployment variable list --deployment-id <DEPLOYMENT_ID> --save --env .env.backup
Create Variables
# Create regular variable
astro deployment variable create --deployment-id <DEPLOYMENT_ID> \
--key API_ENDPOINT \
--value https://api.example.com
# Create secret (masked in UI and logs)
astro deployment variable create --deployment-id <DEPLOYMENT_ID> \
--key API_KEY \
--value secret123 \
--secret
Update Variables
# Update existing variable
astro deployment variable update --deployment-id <DEPLOYMENT_ID> \
--key API_KEY \
--value newsecret
Delete Variables
# Delete variable
astro deployment variable delete --deployment-id <DEPLOYMENT_ID> --key OLD_KEY
Note: Variables are available to DAGs as environment variables. Changes require no redeployment.
Key Metrics from deployment inspect
Focus on these fields when troubleshooting:
- status: HEALTHY vs UNHEALTHY
- runtime_version: Airflow version compatibility
- scheduler_size/scheduler_count: Scheduler capacity
- executor: CELERY, KUBERNETES, or LOCAL
- worker_queues: Worker scaling limits and types
min_worker_count,max_worker_countworker_concurrencyworker_type(resource class)
- resource_quota_cpu/memory: Overall resource limits
- dag_deploy_enabled: Whether DAG-only deploys work
- current_tag: Last deployment version
- is_high_availability: Redundancy enabled
Investigation Best Practices
- Always start with error logs - Most obvious failures appear here
- Check error logs for patterns - Same DAG failing repeatedly? Timing patterns?
- Component-specific troubleshooting:
- Worker logs → task execution details
- Scheduler logs → DAG processing and scheduling
- Webserver logs → UI issues and health checks
- Triggerer logs → deferrable operator issues
- Use
--keywordfor targeted searches - More efficient than reading all logs - The
inspectcommand is your health dashboard - Check it first - Environment variables in
inspectoutput - May reveal configuration issues - Log count default is 500 - Adjust with
-cbased on needs - Don't forget to check deployment time - Recent deploy might have introduced issue
Troubleshooting Quick Reference
| Symptom | Command |
|---|---|
| Deployment shows UNHEALTHY | astro deployment inspect <ID> + --error logs |
| DAG not appearing | --error logs for import errors, check --scheduler logs |
| Tasks failing | --workers logs + search for DAG with --keyword |
| Slow scheduling | --scheduler logs + check inspect for scheduler resources |
| UI not responding | --webserver logs |
| Connection issues | Check variables, search logs for connection name |
| Import errors | --error --keyword "ImportError" + --scheduler logs |
| Out of memory | inspect for resources + --workers --keyword "memory" |
Related Skills
- managing-astro-deployments: Create, update, delete deployments, deploy code
- managing-astro-local-env: Manage local Airflow development environment
- setting-up-astro-project: Initialize and configure Astro projects
FAQ
What does the troubleshooting-astro-deployments skill do?
Troubleshoot Astronomer production deployments with Astro CLI. Use when investigating deployment issues, viewing production logs, analyzing failures, or managing deployment environment variables.
How do I install troubleshooting-astro-deployments?
Run npx skills add https://github.com/astronomer/agents --skill troubleshooting-astro-deployments in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/troubleshooting-astro-deployments/ (personal) or .claude/skills/troubleshooting-astro-deployments/ (project).
Which AI agents can use troubleshooting-astro-deployments?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is troubleshooting-astro-deployments safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains troubleshooting-astro-deployments?
It is published by astronomer in astronomer/agents, and it is an official skill from the maker of the technology it covers. It has 628 recorded installs.
More from astronomer/agents
airflow
astronomer/agents
Queries, manages, and troubleshoots Apache Airflow using the af CLI. Use when working with anything related to Airflow - a DAG, a DAG run, a task log, an import or parse error, a broken DAG, or any Airflow operation. Covers listing and triggering DAGs, retrying runs, reading task logs, diagnosing failures, debugging import and parse errors, checking connections, variables and pools, exploring the REST API, and monitoring health (for example "trigger a pipeline", "retry a run", "list connections", "check Airflow health", "why did my DAG fail"). This is the entrypoint that routes to sibling skills for authoring, testing, deploying, and migrating Airflow 2 to 3. Not for warehouse/SQL analytics on Airflow metadata tables (use analyzing-data); for deep root-cause reports use debugging-dags or airflow-investigation.
managing-astro-local-env
astronomer/agents
Manage local Airflow environment with Astro CLI (Docker and standalone modes). Use when the user wants to start, stop, or restart Airflow, view logs, query the Airflow API, troubleshoot, or fix environment issues. For project setup, see setting-up-astro-project.
analyzing-data
astronomer/agents
Queries the data warehouse with SQL and answers business questions about data. Use when answering anything that needs warehouse data - counts, metrics, trends, aggregations, joins across tables, data lookups, or ad-hoc SQL analysis (for example "who uses X", "how many Y", "show me Z", "find customers", "what is the count").
authoring-dags
astronomer/agents
Workflow and best practices for writing Apache Airflow DAGs. Use when creating a new DAG, write pipeline code, handling questions about DAG patterns and conventions or extending an existing DAG with a follow-up/downstream task. ANY request shaped like 'add a DAG named X', 'write a pipeline', 'add a task that runs after Y', or 'extend the DAG'. For testing and debugging DAGs, see the testing-dags skill.
debugging-dags
astronomer/agents
Comprehensive DAG failure diagnosis and root-cause analysis with structured investigation and prevention recommendations. Use when deep failure investigation is needed, a DAG fails to import/parse or 'airflow dags list' errors on a file; a task or run is failing and must be diagnosed and fixed; requests like 'why did X fail', 'my dag keeps failing — find and fix it', or fixing a broken DAG so it loads cleanly. For simple 'why did it fail / show logs', the airflow skill handles it directly.
testing-dags
astronomer/agents
Complex DAG testing workflows with debugging and fixing cycles. Use for multi-step testing requests like "test this dag and fix it if it fails", "test and debug", "run the pipeline and troubleshoot issues". For simple test requests ("test dag", "run dag"), the airflow entrypoint skill handles it directly. This skill is for iterative test-debug-fix cycles.
Popular devops & cloud skills
microsoft-foundry
microsoft/azure-skills
Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent create, managed harness agent create, GitHub Copilot harness agent, create agent, update agent, add tool to agent, invoke agent, agent insights, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, optimize agent instructions, Agent Optimizer scaffold, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure
azure-diagnostics
microsoft/azure-skills
Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, container app 503 or target port mismatch, troubleshoot functions, function telemetry missing or stopped after a config/connection-string change, troubleshoot AKS, VM RDP, Linux SSH, VM black screen, can't connect to VM, reset VM password, NSG or firewall blocking, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures, resource health, root cause of errors, troubleshoot event hubs, troubleshoot service bus, messaging SDK error, AMQP connection failure, message lock lost, lock renewal during long-running processing, service bus dead letter.
azure-prepare
microsoft/azure-skills
Prepare azd-based Azure projects for deployment: generates azure.yaml, infrastructure (Bicep/Terraform), and Dockerfiles for the Azure Developer CLI (azd) workflow. USE ONLY when the user explicitly wants to use azd as the deployment tool, or the project already has an azure.yaml file. DO NOT USE FOR: non-azd deployments, Python App Service code-only deploys (use python-appservice-deploy), or cross-cloud migration (use azure-cloud-migrate). WHEN: prepare app for azd, create azure.yaml, set up azd infrastructure, modernize app for Azure with azd, deploy with azd, function app, timer trigger, service bus trigger, event-driven function, managed identity, generate Bicep, generate Terraform, create and deploy to Azure.
azure-ai
microsoft/azure-skills
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
azure-deploy
microsoft/azure-skills
Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment", "push to production", "push to cloud", "go live", "ship it", "bicep deploy", "terraform apply", "publish to Azure", "launch on Azure". DO NOT USE WHEN: "create and deploy", "build and deploy", "create a new app", "set up infrastructure", "create and deploy to Azure using Terraform" — use azure-prepare for these.
azure-validate
microsoft/azure-skills
Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless deployment, verify RBAC roles, check role assignments, review managed identity permissions, what-if analysis, validate Container Apps deployment.