Airflow DAG not scheduling: troubleshooting checklist

TL;DR

Walk the scheduling chain in order: the scheduler process must be running, the DAG file must parse without errors, the DAG must be unpaused with a start date in the past and a real schedule. Nine times out of ten the answer is a paused DAG, an import error, or a start date set in the future, and the checklist below finds it fast.

Airflow DAG not scheduling: troubleshooting checklist

Use this when

• a DAG shows no upcoming runs in the UI
• a new DAG never schedules its first run
• runs stopped appearing after a deploy

Not for this skill when

• tasks schedule but fail, that is a task problem not a scheduling problem
• the scheduler itself is crashing, check scheduler logs first
• you are backfilling past dates on purpose, see the backfill skill

Steps

1. Confirm the scheduler process is actually running, since nothing schedules without it:

ps aux | grep -i "airflow scheduler" | grep -v grep

Expected output: a running scheduler process with recent CPU time. No process means nothing will ever schedule, start it before doing anything else.

1. Check the DAG file parses without import errors, because broken files never schedule:

airflow dags list-import-errors

Expected output: an empty list, or your DAG file listed with its traceback. Fix any import error first, everything downstream of a broken parse is moot.

1. Verify the DAG is visible to the scheduler and check its pause state in the UI:

airflow dags list | grep my_dag

Expected output: your DAG listed by its exact dag_id. Then check the UI toggle, a paused DAG schedules nothing by design and new DAGs often land paused.

1. Inspect the schedule, start date, and pause state in one view:

airflow dags show my_dag | head -30

Expected output: the DAG's schedule, start date, and pause state. A future start_date or an unintended schedule of None explains the silence completely.

1. Look at recent scheduler logs for decisions about your DAG:

ls ~/airflow/logs/scheduler/ | tail -5

Expected output: recent scheduler log files exist. Search them for your dag_id to see parse results and scheduling decisions, which tell you what the scheduler thinks is happening.

1. Trigger a manual run to confirm the DAG itself works end to end:

airflow dags trigger my_dag

Expected output: a new DAG run appears in the UI. If manual triggers work but schedules do not, the problem is purely in scheduling config, not in the DAG logic.

Variant phrasings

airflow dag not running on schedule

Work the checklist top to bottom without skipping. Import errors and paused DAGs cover the large majority of cases.

new airflow dag never scheduled

Almost always a future start_date or the file landing outside the scanned dags folder. Steps 2 and 4 catch both in under a minute.

airflow dag stopped scheduling after a deploy

A deploy introduced an import error or the scheduler never picked up the new file. Steps 1 and 2 come first, then check the dags folder the scheduler actually scans.

Why it happens

Scheduling is a pipeline: the scheduler parses files, builds runs for unpaused DAGs with valid schedules, then queues tasks. A break at any stage looks identical from the UI, which is just an empty calendar with no explanation. The checklist walks the pipeline in order so the first failure you find is the real one.

Edge cases

• catchup=False with an old start_date schedules only the latest interval. That is working as configured, not broken.
• Timezones: a naive start_date can read as future in UTC. Use timezone-aware datetimes everywhere.
• maxactiveruns=1 with one stuck run blocks all future runs. Clear the stuck run and scheduling resumes.
• Two schedulers running at once fight over the metadata DB. Find and kill the duplicate before anything else.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_JhzVbZ4XV326stIp-p27Lw