dbt-labs/dbt-core · error · AdapterError

Cannot apply incremental predicates with '{strategy}' strate

Error message

Cannot apply incremental predicates with '{strategy}' strategy.

What it means

Incremental predicates (predicates applied during the incremental run) are only meaningful for the delete_insert and microbatch strategies on ClickHouse. validate_incremental_strategy rejects any model that supplies incremental_predicates together with one of the other strategies (legacy, append, insert_overwrite).

Source

Thrown at crates/dbt-adapter/src/metadata/clickhouse/mod.rs:917

    ) {
        return err(format!(
            "The incremental strategy '{strategy}' is not valid for ClickHouse."
        ));
    }
    if matches!(strategy, "delete_insert" | "microbatch") && !has_lw_deletes {
        return err(format!(
            "'{strategy}' strategy requires lightweight deletes, but the required setting \
             '{ND_MUTATION_SETTING}' could not be enabled on this ClickHouse server \
             (see the warnings logged at connection time)."
        ));
    }
    if matches!(strategy, "delete_insert" | "microbatch") && !has_unique_key {
        return err(format!(
            "'{strategy}' strategy requires a non-empty 'unique_key'."
        ));
    }
    if !matches!(strategy, "delete_insert" | "microbatch") && has_predicates {
        return err(format!(
            "Cannot apply incremental predicates with '{strategy}' strategy."
        ));
    }
    if strategy == "insert_overwrite" && !has_partition_by {
        return err(format!(
            "'{strategy}' strategy requires non-empty 'partition_by'. Current partition_by is None."
        ));
    }
    if strategy == "insert_overwrite" && has_unique_key {
        return err(format!(
            "'{strategy}' strategy does not support unique_key."
        ));
    }
    Ok(())
}

/// Mirrors column.py `ClickHouseColumnChanges` as a Jinja value: none when
/// there are no changes (its `__bool__`, so `{% if column_changes %}` skips),

View on GitHub (pinned to 0267ce9170)

Solutions

1. Remove incremental_predicates from the model config, or
2. Change incremental_strategy to 'delete_insert' or 'microbatch' where predicates are supported
3. For partition-scoped processing with insert_overwrite, use partition_by instead of predicates

Example fix

// before
{{ config(materialized='incremental', incremental_strategy='insert_overwrite', incremental_predicates=["status = 'active'"]) }}
// after
{{ config(materialized='incremental', incremental_strategy='delete_insert', unique_key='id', incremental_predicates=["status = 'active'"]) }}

if cfg.incremental_predicates.is_some()
    && !matches!(cfg.incremental_strategy.as_str(), "delete_insert" | "microbatch") {
    panic!("incremental_predicates only valid with delete_insert or microbatch");
}

When it happens

Trigger: Setting incremental_predicates on a ClickHouse incremental model whose incremental_strategy is 'legacy', 'append', or 'insert_overwrite'; inheriting predicates from a base config while overriding the strategy.

Common situations: Copying a Snowflake/Postgres model config (where predicates pair with delete strategies) onto ClickHouse with a different strategy; combining insert_overwrite partition pruning with leftover predicates from a template.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• The incremental strategy '{strategy}' is not valid for Click
• '{strategy}' strategy requires lightweight deletes, but the
• '{strategy}' strategy requires a non-empty 'unique_key'.
• '{strategy}' strategy requires non-empty 'partition_by'. Cur
• '{strategy}' strategy does not support unique_key.

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