Heuristic:Astronomer Astronomer cosmos Deprecation Migration Paths

Knowledge Sources	astronomer-cosmos Cosmos CHANGELOG
Domains	Debugging, Data_Orchestration
Last Updated	2026-02-07 17:00 GMT

Overview

Summary of deprecated Cosmos APIs with clear migration paths targeting Cosmos 2.0 removal, including config parameters, operator arguments, and load modes.

Description

Cosmos follows a structured deprecation policy where features are deprecated with warnings in minor releases and removed in the next major release (2.0). Each deprecation includes a DeprecationWarning with specific migration instructions. Understanding these migrations is critical for teams planning upgrades to avoid breaking changes.

Usage

Consult this heuristic when upgrading Cosmos versions or when you see DeprecationWarning messages in Airflow logs. Each entry provides the old API, the replacement, and the target removal version.

The Insight (Rule of Thumb)

RenderConfig.env_vars (deprecated since 1.3, removed in 2.0): Use ProjectConfig.env_vars instead.
RenderConfig.dbt_deps (deprecated since 1.9, removed in 2.0): Use ProjectConfig.install_dbt_deps instead.
BaseProfileMapping.disable_event_tracking (deprecated since 1.3, removed in 2.0): Use dbt_config_vars=DbtProfileConfigVars(send_anonymous_usage_stats=False).
LoadMode.CUSTOM (deprecated, removed in 2.0): Use LoadMode.DBT_MANIFEST or LoadMode.DBT_LS.
DbtDocsS3Operator.aws_conn_id (deprecated, removed in 2.0): Use connection_id parameter.
DbtDocsAzureStorageOperator.azure_conn_id (deprecated, removed in 2.0): Use connection_id parameter.
DbtDocsAzureStorageOperator.container_name (deprecated, removed in 2.0): Use bucket_name parameter.
DbtDepsOperator (fully removed): Use the install_deps flag in dbt_args instead.
schema in task_args (deprecated): Use profile_args instead.

Reasoning

Deprecation warning from cosmos/config.py:108-116:

warnings.warn(
    "RenderConfig.env_vars is deprecated since Cosmos 1.3 and will be removed "
    "in Cosmos 2.0. Use ProjectConfig.env_vars instead.",
    DeprecationWarning,
)

LoadMode.CUSTOM deprecation from cosmos/dbt/graph.py:895-899:

warnings.warn(
    "Using `load_method` = `LoadMode.CUSTOM` is deprecated in current version "
    "and will be removed in Cosmos 2.0",
    DeprecationWarning,
)

DbtDepsOperator removal from cosmos/operators/local.py:1378-1380:

raise DeprecationWarning(
    "The DbtDepsOperator has been deprecated. Please use the `install_deps` "
    "flag in dbt_args instead."
)

Connection ID migration from cosmos/operators/local.py:1230-1234:

warnings.warn(
    "Please, use `connection_id` instead of `aws_conn_id`. The argument "
    "`aws_conn_id` will be deprecated in Cosmos 2.0",
    DeprecationWarning,
)

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment