A new DAG file is in the folder but the DAG is not in the list. Most of the time Airflow has not read the file yet, or it read it and found an error. Two causes are silent: they produce no error at all. Four commands tell you which case you are in.

Copy and paste

airflow config get-value core dags_folder     # 1. is the file in this folder?
airflow dags list-import-errors               # 2. did the file fail to import?
airflow dags list | grep my_dag               # 3. did Airflow register the DAG?
airflow dags reserialize                      # 4. read every file now, instead of waiting

Run them with the same AIRFLOW_HOME and virtual environment as the running Airflow, or they read a different configuration.

The checklist

1. Wait, or force a scan. The DAG processor looks for new files every 300 seconds ([dag_processor] refresh_interval) and rereads changed files every 30 seconds (min_file_process_interval). A brand-new file can take five minutes to appear. airflow dags reserialize reads everything at once.

2. Check the folder. The file must be inside dags_folder, $AIRFLOW_HOME/dags by default. A file in a folder with a similar name, or under a different AIRFLOW_HOME, is never read.

3. Look for an import error. A missing package, a syntax error or a wrong import path stops the whole file. The UI shows a banner with the import errors, and the command prints the traceback:

bundle_name | filepath    | error
dags-folder | g_broken.py | Traceback (most recent call last):
            |             |   File ".../dags/g_broken.py", line 3, in <module>
            |             |     import not_installed_package
            |             | ModuleNotFoundError: No module named 'not_installed_package'

After an upgrade to Airflow 3 a common cause is an import that no longer exists; see old and new import paths.

4. Call the decorated function. With @dag, the DAG exists only if the function is called at the end of the file. Without the last line there is no error, and no DAG:

@dag(schedule=None, start_date=pendulum.datetime(2026, 1, 1, tz="UTC"))
def my_dag():
    ...

my_dag()   # without this line Airflow finds nothing

5. Mention Airflow in the file. With dag_discovery_safe_mode, on by default, Airflow skips any file whose text does not contain the word airflow together with dag or asset, ignoring case. A file that builds DAGs through a helper module, without importing anything from Airflow itself, is skipped silently. Adding a comment such as # airflow dag is enough.

6. Check .airflowignore. A .airflowignore file in the DAGs folder excludes paths that match its patterns, which are glob patterns by default in Airflow 3. A broad pattern such as *test* also hides latest_orders.py.

7. Is the DAG processor running? In Airflow 3 the DAG processor is a separate component. airflow standalone starts it for you. If you start the scheduler and the API server yourself, start airflow dag-processor too, or no file is ever read.

8. Slow imports. A file must load within 30 seconds (dagbag_import_timeout). Queries, API calls or large imports at the top level of the file can exceed it, and the file then appears among the import errors. Move that work inside the tasks.

It shows up but does not run

New DAGs start paused. A paused DAG is in the list, but the scheduler creates no runs for it. Unpause it with the toggle in the UI or with airflow dags unpause my_dag.

Tested with Airflow 3.3.2.

References