{"record":{"id":"94fb1e0ebc0e736a","repo":"dbt-labs/dbt-core","slug":"strategy-strategy-requires-lightweight-deletes","errorCode":null,"errorMessage":"'{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).","messagePattern":"'(.+?)' strategy requires lightweight deletes, but the required setting '(.+?)' could not be enabled on this ClickHouse server \\(see the warnings logged at connection time\\)\\.","errorType":"validation","errorClass":"AdapterError","httpStatus":null,"severity":"error","filePath":"crates/dbt-adapter/src/metadata/clickhouse/mod.rs","lineNumber":905,"sourceCode":"/// cross-config checks, with Python-exact messages.\npub(crate) fn validate_incremental_strategy(\n    strategy: &str,\n    has_predicates: bool,\n    has_unique_key: bool,\n    has_partition_by: bool,\n    has_lw_deletes: bool,\n) -> AdapterResult<()> {\n    let err = |msg: String| Err(AdapterError::new(AdapterErrorKind::Configuration, msg));\n    if !matches!(\n        strategy,\n        \"legacy\" | \"append\" | \"delete_insert\" | \"insert_overwrite\" | \"microbatch\"\n    ) {\n        return err(format!(\n            \"The incremental strategy '{strategy}' is not valid for ClickHouse.\"\n        ));\n    }\n    if matches!(strategy, \"delete_insert\" | \"microbatch\") && !has_lw_deletes {\n        return err(format!(\n            \"'{strategy}' strategy requires lightweight deletes, but the required setting \\\n             '{ND_MUTATION_SETTING}' could not be enabled on this ClickHouse server \\\n             (see the warnings logged at connection time).\"\n        ));\n    }\n    if matches!(strategy, \"delete_insert\" | \"microbatch\") && !has_unique_key {\n        return err(format!(\n            \"'{strategy}' strategy requires a non-empty 'unique_key'.\"\n        ));\n    }\n    if !matches!(strategy, \"delete_insert\" | \"microbatch\") && has_predicates {\n        return err(format!(\n            \"Cannot apply incremental predicates with '{strategy}' strategy.\"\n        ));\n    }\n    if strategy == \"insert_overwrite\" && !has_partition_by {\n        return err(format!(\n            \"'{strategy}' strategy requires non-empty 'partition_by'. Current partition_by is None.\"","sourceCodeStart":887,"sourceCodeEnd":923,"githubUrl":"https://github.com/dbt-labs/dbt-core/blob/0267ce9170576975b76b64ce856b2e5848e96617/crates/dbt-adapter/src/metadata/clickhouse/mod.rs#L887-L923","documentation":"The delete_insert and microbatch incremental strategies on ClickHouse are implemented with lightweight deletes, which need the server setting identified by ND_MUTATION_SETTING (allow_deexperimental_lightweight_delete / related mutation setting) to be enabled. If the adapter could not enable it on the connected server, validation fails before the run. The message points to warnings logged at connection time, which contain the underlying reason.","triggerScenarios":"Running an incremental model with incremental_strategy='delete_insert' or 'microbatch' against a ClickHouse server where the lightweight-delete mutation setting could not be applied — typically old ClickHouse versions, managed offerings that restrict settings, or a user without permission to change server settings.","commonSituations":"Connecting to an outdated self-hosted ClickHouse that predates lightweight deletes; ClickHouse Cloud or a managed service where SET is blocked; running as a restricted user without setting-grant permissions.","solutions":["Upgrade the ClickHouse server to a version supporting lightweight deletes","Check the connection-time warnings in the logs for why the setting could not be enabled and fix that cause","Ensure the connecting user has permission to change the required setting, or have an admin enable it","Switch incremental_strategy to 'append' or 'legacy' if lightweight deletes cannot be enabled"],"exampleFix":"# before\nmodels:\n  - name: my_model\n    config:\n      materialized: incremental\n      incremental_strategy: delete_insert\n# after (server cannot enable lightweight deletes)\nmodels:\n  - name: my_model\n    config:\n      materialized: incremental\n      incremental_strategy: append","handlingStrategy":"validation","validationCode":"// before running delete_insert/microbatch, confirm the server supports the setting\n// and that connection logs show no warnings about enabling it\nassert!(connection_info.supports_lightweight_deletes);","typeGuard":null,"tryCatchPattern":"match validate_incremental_strategy(...) {\n    Err(AdapterError { kind: Configuration, msg, .. }) if msg.contains(\"lightweight deletes\") => {\n        fallback_to_append_strategy()\n    }\n    other => other,\n}","preventionTips":["Run a recent ClickHouse version with lightweight-delete support","Check connection-time warnings at startup, not first failure","Confirm the db user can SET the required server setting","Prefer append strategy on restricted managed offerings"],"tags":["clickhouse","dbt","configuration","server-settings"],"backgroundTag":"feature-not-enabled","analyzedSha":"0267ce9170576975b76b64ce856b2e5848e96617","analyzedAt":"2026-09-07T21:53:39.732Z","contentChangedAt":"2026-09-07T21:53:39.732Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}