Behavior changes
Behavior change flags let you control when to adopt new runtime behaviors in dbt. They're configured in your dbt_project.yml file.
Several behavior change flags on the dbt platform Latest release track are planned to be enabled by default on June 23, 2026. Refer to Flags reaching maturity to see which flags are affected, how they may impact your project, and how to opt out before the change takes effect.
Since behavior change flags are different from other dbt changes, it's important to understand the difference:
- Deprecation warnings — Features in your project code that will stop working (behavior flags often control when these become errors)
- Deprecated CLI flags — Command-line flags being removed in dbt Fusion
See the Changes overview for a quick comparison.
If you're upgrading to dbt Fusion or dbt Core v2, a subset of behavior change flags are removed and their new behavior is always enabled.
Most flags exist to configure runtime behaviors with multiple valid choices. The right choice may vary based on the environment, user preference, or the specific invocation.
Another category of flags provides existing projects with a migration window for runtime behaviors that are changing in newer releases of dbt. These flags help us achieve a balance between these goals, which can otherwise be in tension, by:
- Providing a better, more sensible, and more consistent default behavior for new users/projects.
- Providing a migration window for existing users/projects — nothing changes overnight without warning.
- Providing maintainability of dbt software. Every fork in behavior requires additional testing & cognitive overhead that slows future development. These flags exist to facilitate migration from "current" to "better," not to stick around forever.
These flags go through three phases of development:
- Introduction (disabled by default): dbt adds logic to support both 'old' and 'new' behaviors. The 'new' behavior is gated behind a flag, disabled by default, preserving the old behavior. For flags still in the introduction phase, refer to Introduced behavior flags.
- Maturity (enabled by default): The default value of the flag is switched, from
falsetotrue, enabling the new behavior by default. Users can preserve the 'old' behavior and opt out of the 'new' behavior by setting the flag tofalsein their projects. They may see deprecation warnings when they do so. For flags that have already reached maturity, refer to Mature behavior flags. - Removal (generally enabled): After marking the flag for deprecation, we remove it along with the 'old' behavior it supported from the dbt codebases. We aim to support most flags indefinitely, but we're not committed to supporting them forever. If we choose to remove a flag, we'll offer significant advance notice. For flags removed in dbt Core v2, refer to Removed behavior flags.
What is a behavior change?
The same dbt project code and the same dbt commands return one result before the behavior change, and they return a different result after the behavior change.
Examples of behavior changes:
- dbt begins raising a validation error that it didn't previously.
- dbt changes the signature of a built-in macro. Your project has a custom reimplementation of that macro. This could lead to errors, because your custom reimplementation will be passed arguments it cannot accept.
- A dbt adapter renames or removes a method that was previously available on the
{{ adapter }}object in the dbt-Jinja context. - dbt makes a breaking change to contracted metadata artifacts by deleting a required field, changing the name or type of an existing field, or removing the default value of an existing field (README).
- dbt removes one of the fields from structured logs.
The following are not behavior changes:
- Fixing a bug where the previous behavior was defective, undesirable, or undocumented.
- dbt begins raising a warning that it didn't previously.
- dbt updates the language of human-friendly messages in log events.
- dbt makes a non-breaking change to contracted metadata artifacts by adding a new field with a default, or deleting a field with a default (README).
The vast majority of changes are not behavior changes. Because introducing these changes does not require any action on the part of users, they are included in continuous releases of dbt and patch releases of dbt Core.
By contrast, behavior change migrations happen slowly, over the course of months, facilitated by behavior change flags. The flags are loosely coupled to the specific dbt runtime version. By setting flags, users have control over opting in (and later opting out) of these changes.
Behavior change flags
These flags must be set in the flags dictionary in dbt_project.yml. They configure behaviors closely tied to project code, which means they should be defined in version control and modified through pull or merge requests, with the same testing and peer review.
The following example displays the current flags and their current default values in the latest dbt and dbt Core versions. To opt out of a specific behavior change, set the values of the flag to false in dbt_project.yml. You will continue to see warnings for legacy behaviors you've opted out of, until you either:
- Resolve the issue (by switching the flag to
true) - Silence the warnings using the
warn_error_options.silenceflag
Here's an example of the available behavior change flags with their default values:
flags:
require_explicit_package_overrides_for_builtin_materializations: true
require_resource_names_without_spaces: true
source_freshness_run_project_hooks: true
skip_nodes_if_on_run_start_fails: false
state_modified_compare_more_unrendered_values: false
require_yaml_configuration_for_mf_time_spines: false
require_batched_execution_for_custom_microbatch_strategy: false
require_nested_cumulative_type_params: false
validate_macro_args: false
require_all_warnings_handled_by_warn_error: false
require_generic_test_arguments_property: true
require_unique_project_resource_names: false
require_ref_searches_node_package_before_root: false
require_valid_schema_from_generate_schema_name: false
enable_truthy_nulls_equals_macro: false
require_sql_header_in_test_configs: false
require_corrected_analysis_fqns: false
require_source_and_semantic_model_names_without_spaces: false
allow_jinja_file_extensions: false
latest_version_pointer_enabled_by_default: false
dbt Core behavior changes
This table outlines which month of the Latest release track in dbt and which version of dbt Core contains the behavior change's introduction (disabled by default) or maturity (enabled by default).
| Loading table... |
When a maturity date has not yet been set (shown as -), we have not yet determined the exact date when the flag's default value will change. Affected users will see deprecation warnings in the meantime, and they will receive emails providing advance warning ahead of the maturity date. In the meantime, if you are seeing a deprecation warning, you can either:
- Migrate your project to support the new behavior, and then set the flag to
trueto stop seeing the warnings. - Explicitly set the flag to
false. You will continue to see warnings, and you will retain the legacy behavior even after the maturity date (when the default value changes).
dbt adapter behavior changes
This table outlines which version of the dbt adapter contains the behavior change's introduction (disabled by default) or maturity (enabled by default).
| Loading table... |
Was this page helpful?
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.
