Heuristic:Astronomer Astronomer cosmos Static Parser Hang Workaround
| Knowledge Sources | |
|---|---|
| Domains | Debugging, Data_Orchestration |
| Last Updated | 2026-02-07 17:00 GMT |
Overview
Workaround for dbtRunner task hangs: pass --no-static-parser flag when using dbtRunner with dbt >= 1.5.6 to prevent execution deadlocks.
Description
When Cosmos uses the dbtRunner invocation mode, the dbt project is parsed during both DAG scheduling (to build the task graph) and task execution (to run the actual command). Because Cosmos copies the dbt project to temporary directories, the temp path used at parse time differs from the path at execution time. This path mismatch interferes with dbt's static parser caching, which can cause the task to hang indefinitely, especially on Airflow 2.x. The --no-static-parser flag disables dbt's static parsing optimization, trading a small parse-time increase for reliable execution.
Usage
This heuristic is automatically applied by Cosmos when InvocationMode.DBT_RUNNER is active and dbt-core version >= 1.5.6. No manual configuration is needed. However, understanding this behavior is critical when debugging task hangs or investigating slow dbt executions.
The Insight (Rule of Thumb)
- Action: Cosmos automatically appends
--no-static-parserto dbt flags when using dbtRunner with dbt >= 1.5.6. - Value: Prevents indefinite task hangs.
- Trade-off: Slightly slower dbt parsing (static parser optimization disabled), but eliminates the risk of execution deadlocks.
- Compatibility: Only applies to dbt >= 1.5.6; earlier versions do not have the static parser feature.
Reasoning
The root cause was identified during PR #1484 investigation. The dbtRunner maintains internal state about parsed projects, keyed by the project path. When the path changes between scheduling (parse) and execution (run) due to temp directory creation, the static parser attempts to reconcile its cached state with the new path and can enter a deadlock.
From cosmos/operators/local.py:521-528:
if Version(dbt_version) >= Version("1.5.6"):
# PR #1484 introduced the use of dbtRunner during DAG parsing. As a result,
# invoking dbtRunner again during task execution can lead to task hangs—
# especially on Airflow 2.x. Investigation revealed that the issue stems from
# how dbtRunner handles static parsing. Cosmos copies the dbt project to
# temporary directories, and the use of different temp paths between parsing
# and execution appears to interfere with dbt's static parsing behavior.
# As a workaround, passing the --no-static-parser flag avoids these hangs
# and ensures reliable task execution.
dbt_flags.append("--no-static-parser")
The version check from cosmos/operators/local.py:518-519:
if self.invocation_mode == InvocationMode.DBT_RUNNER:
from dbt.version import __version__ as dbt_version