dbt-labs/dbt-core · error

insert_overwrite: use_replace_on_for_insert_overwrite is…

Error message

insert_overwrite: use_replace_on_for_insert_overwrite is enabled but this cluster's DBR version does not support REPLACE ON (requires DBR 17.1+). Falling back to legacy INSERT OVERWRITE.

What it means

Error "insert_overwrite: use_replace_on_for_insert_overwrite is enabled but this cluster's DBR version does not support REPLACE ON (requires DBR 17.1+). Falling back to legacy INSERT OVERWRITE." thrown in dbt-labs/dbt-core.

Solutions

1. Upgrade the cluster to DBR 17.1+ so REPLACE ON is available for insert_overwrite
2. Accept the documented fallback to legacy INSERT OVERWRITE on older DBR clusters
3. Disable use_replace_on_for_insert_overwrite to silence the capability check

When it happens

Trigger: Thrown at crates/dbt-loader/src/dbt_macro_assets/dbt-databricks/macros/materializations/incremental/strategies.sql:39 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of dbt-labs/dbt-core@0267ce9170 (2026-09-07). Data as JSON: /api/errors/51bf098d9338c5b8. Report an issue: GitHub.

Appendix: source

Thrown at crates/dbt-loader/src/dbt_macro_assets/dbt-databricks/macros/materializations/incremental/strategies.sql:39

{% macro get_incremental_replace_where_sql(arg_dict) %}

  {{ return(adapter.dispatch('get_incremental_replace_where_sql', 'dbt')(arg_dict)) }}

{% endmacro %}

{% macro databricks__get_insert_overwrite_merge_sql(target, source, dest_columns, predicates, include_sql_header) %}
    {{ return(get_insert_overwrite_sql(source, target)) }}
{% endmacro %}

{% macro get_insert_overwrite_sql(source_relation, target_relation) %}
    {%- if adapter.is_cluster() -%}
        {#-- Clusters: Check DBR capability for REPLACE ON (DBR 17.1+) --#}
        {%- if adapter.has_dbr_capability('replace_on') -%}
            {{ get_insert_replace_on_sql(source_relation, target_relation) }}
        {%- else -%}
            {%- if adapter.behavior.use_replace_on_for_insert_overwrite -%}
                {{ exceptions.warn("insert_overwrite: use_replace_on_for_insert_overwrite is enabled but this cluster's DBR version does not support REPLACE ON (requires DBR 17.1+). Falling back to legacy INSERT OVERWRITE.") }}
            {%- endif -%}
            {%- set has_insert_by_name = adapter.has_dbr_capability('insert_by_name') -%}
            insert overwrite table {{ target_relation }}
            {{ partition_cols(label="partition") }}
            {%- if has_insert_by_name %} by name{% endif %}
            select * from {{ source_relation }}
        {%- endif -%}
    {%- else -%}
        {%- if adapter.behavior.use_replace_on_for_insert_overwrite -%}
            {{ get_insert_replace_on_sql(source_relation, target_relation) }}
        {%- else -%}
            {#-- Behavior flag disabled, use legacy DPO INSERT OVERWRITE --#}
            {%- set has_insert_by_name = adapter.has_dbr_capability('insert_by_name') -%}
            insert overwrite table {{ target_relation }}
            {{ partition_cols(label="partition") }}
            {%- if has_insert_by_name %} by name{% endif %}
            select * from {{ source_relation }}
        {%- endif -%}

View on GitHub (pinned to 0267ce9170)