dbt-labs/dbt-core · error · AdapterError

'{strategy}' strategy requires non-empty 'partition_by'. Cur

Error message

'{strategy}' strategy requires non-empty 'partition_by'. Current partition_by is None.

What it means

The insert_overwrite incremental strategy on ClickHouse works by replacing whole partitions, so a non-empty partition_by config is mandatory. validate_incremental_strategy raises this Configuration error when insert_overwrite is selected but partition_by is None.

Source

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

    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),
/// else a map; errors when the strategy cannot reconcile the changes.
pub(crate) fn column_changes_value(
    on_schema_change: &str,
    source: Vec<Column>,
    target: Vec<Column>,

View on GitHub (pinned to 0267ce9170)

Solutions

Add a non-empty partition_by config (e.g. a date column) to the model
Ensure the partition_by expression is valid for ClickHouse (no mutable functions like now())
If the table cannot be partitioned, use 'append' or 'delete_insert' instead

Example fix

// before
{{ config(materialized='incremental', incremental_strategy='insert_overwrite') }}
// after
{{ config(materialized='incremental', incremental_strategy='insert_overwrite', partition_by='toDate(event_ts)') }}

Defensive patterns

Strategy: validation

Validate before calling

if cfg.incremental_strategy == "insert_overwrite" {
    assert!(!cfg.partition_by.as_ref().map_or(true, |p| p.is_empty()), "partition_by required");
}

Prevention

Always pair insert_overwrite with a valid partition_by expression
Use immutable partition expressions (avoid now())
Confirm the target table supports the chosen partition key

When it happens

Trigger: Setting incremental_strategy='insert_overwrite' on a ClickHouse incremental model without a partition_by column/expression, or with an empty partition_by value.

Common situations: Switching a model from append to insert_overwrite without adding partitioning; copying the strategy from an example that assumed a partitioned table.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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