dbt-labs/dbt-core · error · AdapterError

The incremental strategy '{strategy}' is not valid for Click

Error message

The incremental strategy '{strategy}' is not valid for ClickHouse.

What it means

ClickHouse incremental materializations only support the strategies 'legacy', 'append', 'delete_insert', 'insert_overwrite', and 'microbatch'. validate_incremental_strategy rejects any other value at configuration time with a Configuration adapter error. This is an upfront guard so users get a clear message instead of failing mid-run with generated SQL.

Source

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

    };
    strategy.replace('+', "_")
}

/// Mirrors impl.py `validate_incremental_strategy`: ClickHouse-specific
/// cross-config checks, with Python-exact messages.
pub(crate) fn validate_incremental_strategy(
    strategy: &str,
    has_predicates: bool,
    has_unique_key: bool,
    has_partition_by: bool,
    has_lw_deletes: bool,
) -> AdapterResult<()> {
    let err = |msg: String| Err(AdapterError::new(AdapterErrorKind::Configuration, msg));
    if !matches!(
        strategy,
        "legacy" | "append" | "delete_insert" | "insert_overwrite" | "microbatch"
    ) {
        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."

View on GitHub (pinned to 0267ce9170)

Solutions

1. Change the model config to one of: legacy, append, delete_insert, insert_overwrite, microbatch
2. If porting from another adapter, map the strategy to the ClickHouse equivalent (e.g. delete+insert -> delete_insert)
3. Omit incremental_strategy entirely to use the adapter default

Example fix

// before
{{ config(materialized='incremental', incremental_strategy='delete+insert') }}
// after
{{ config(materialized='incremental', incremental_strategy='delete_insert') }}

const VALID: &[&str] = &["legacy", "append", "delete_insert", "insert_overwrite", "microbatch"];
assert!(VALID.contains(&cfg.incremental_strategy.as_str()), "invalid strategy for ClickHouse");

fn is_valid_clickhouse_strategy(s: &str) -> bool {
    matches!(s, "legacy" | "append" | "delete_insert" | "insert_overwrite" | "microbatch")
}

When it happens

Trigger: Configuring a dbt ClickHouse model with config materialized='incremental' and incremental_strategy set to any string outside the five allowed values (e.g. 'delete+insert', 'merge', 'append_plus', or a strategy copied from another adapter like Snowflake's 'delete+insert' or BigQuery's 'merge').

Common situations: Porting a dbt project from another warehouse to ClickHouse without updating incremental_strategy; a typo in the strategy name; following outdated blog posts that predate the current strategy set.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• '{strategy}' strategy requires lightweight deletes, but the
• '{strategy}' strategy requires a non-empty 'unique_key'.
• Cannot apply incremental predicates with '{strategy}' strate
• '{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/73ab088abb5245be. Report an issue: GitHub.