apache/seatunnel · error · ClickhouseConnectorException

COMMON_ILLEGAL_ARGUMENT

COMMON_ILLEGAL_ARGUMENT

Error message

split mode only support table which engine is 'Distributed' engine at now

What it means

This error is thrown when the ClickHouse sink is configured with split_mode = true but the target table's engine is not 'Distributed'. Split mode writes directly to local shards of a Distributed table, so it only makes sense for Distributed engines. The sink checks the table engine via SHOW CREATE TABLE metadata at writer creation time and fails fast.

Source

Thrown at seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/sink/client/ClickhouseSink.java:113

        readonlyConfig
                .get(CLICKHOUSE_CONFIG)
                .forEach((key, value) -> clickhouseProperties.put(key, String.valueOf(value)));

        clickhouseProperties.put("user", readonlyConfig.get(USERNAME));
        clickhouseProperties.put("password", readonlyConfig.get(PASSWORD));
        ClickhouseProxy proxy = new ClickhouseProxy(nodes.get(0));

        Map<String, String> tableSchema = proxy.getClickhouseTableSchema(readonlyConfig.get(TABLE));
        String shardKey = null;
        String shardKeyType = null;
        ClickhouseTable table =
                proxy.getClickhouseTable(
                        proxy.getClickhouseConnection(),
                        readonlyConfig.get(DATABASE),
                        readonlyConfig.get(TABLE));
        if (readonlyConfig.get(SPLIT_MODE)) {
            if (!"Distributed".equals(table.getEngine())) {
                throw new ClickhouseConnectorException(
                        CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT,
                        "split mode only support table which engine is "
                                + "'Distributed' engine at now");
            }
            if (readonlyConfig.getOptional(SHARDING_KEY).isPresent()) {
                shardKey = readonlyConfig.get(SHARDING_KEY);
                shardKeyType = tableSchema.get(shardKey);
            }
        }
        ShardMetadata metadata =
                new ShardMetadata(
                        shardKey,
                        shardKeyType,
                        table.getSortingKey(),
                        readonlyConfig.get(DATABASE),
                        readonlyConfig.get(TABLE),
                        table.getEngine(),
                        readonlyConfig.get(SPLIT_MODE),

View on GitHub (pinned to cf67b549a7)

Solutions

Set split_mode = false in the sink config, or remove it (default is false)
Point table/database at an actual Distributed table if split mode is desired
Convert the target table to a Distributed engine table over the underlying MergeTree

Example fix

// before
sink {
  Clickhouse {
    split_mode = true
    table = "my_merge_tree_table"
  }
}
// after
sink {
  Clickhouse {
    split_mode = false
    table = "my_merge_tree_table"
  }
}

Defensive patterns

Strategy: validation

Validate before calling

// run before enabling split mode
String engine = clickhouse.tableEngine(database, table);
if (!"Distributed".equals(engine)) throw new IllegalArgumentException(
    "split_mode requires a Distributed table, got: " + engine);

Try / catch

try { createSinkWriter(config); } catch (ClickhouseConnectorException e) {
  if (e.getCode().equals(CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT)) { /* disable split_mode or fix table */ }
}

Prevention

Only enable split_mode for tables whose engine is Distributed
Default split_mode to false unless you verified the engine
Query SHOW CREATE TABLE / system.tables.engine before deploying the config

When it happens

Trigger: Setting SPLIT_MODE=true in the ClickHouse sink config while the target table is a MergeTree, ReplicatedMergeTree, or any non-Distributed engine; the check happens in ClickhouseSink.createWriter after fetching table metadata.

Common situations: Users enable split mode to parallelize writes into a plain MergeTree table, or the table was migrated/changed from Distributed to MergeTree; also misconfiguring database/table pointing to the wrong (non-distributed) table.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/9ff20661a0257c7e. Report an issue: GitHub.