{"record":{"id":"9ff20661a0257c7e","repo":"apache/seatunnel","slug":"common-illegal-argument-9ff206","errorCode":"COMMON_ILLEGAL_ARGUMENT","errorMessage":"split mode only support table which engine is 'Distributed' engine at now","messagePattern":"split mode only support table which engine is 'Distributed' engine at now","errorType":"error_code","errorClass":"ClickhouseConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/sink/client/ClickhouseSink.java","lineNumber":113,"sourceCode":"        readonlyConfig\n                .get(CLICKHOUSE_CONFIG)\n                .forEach((key, value) -> clickhouseProperties.put(key, String.valueOf(value)));\n\n        clickhouseProperties.put(\"user\", readonlyConfig.get(USERNAME));\n        clickhouseProperties.put(\"password\", readonlyConfig.get(PASSWORD));\n        ClickhouseProxy proxy = new ClickhouseProxy(nodes.get(0));\n\n        Map<String, String> tableSchema = proxy.getClickhouseTableSchema(readonlyConfig.get(TABLE));\n        String shardKey = null;\n        String shardKeyType = null;\n        ClickhouseTable table =\n                proxy.getClickhouseTable(\n                        proxy.getClickhouseConnection(),\n                        readonlyConfig.get(DATABASE),\n                        readonlyConfig.get(TABLE));\n        if (readonlyConfig.get(SPLIT_MODE)) {\n            if (!\"Distributed\".equals(table.getEngine())) {\n                throw new ClickhouseConnectorException(\n                        CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT,\n                        \"split mode only support table which engine is \"\n                                + \"'Distributed' engine at now\");\n            }\n            if (readonlyConfig.getOptional(SHARDING_KEY).isPresent()) {\n                shardKey = readonlyConfig.get(SHARDING_KEY);\n                shardKeyType = tableSchema.get(shardKey);\n            }\n        }\n        ShardMetadata metadata =\n                new ShardMetadata(\n                        shardKey,\n                        shardKeyType,\n                        table.getSortingKey(),\n                        readonlyConfig.get(DATABASE),\n                        readonlyConfig.get(TABLE),\n                        table.getEngine(),\n                        readonlyConfig.get(SPLIT_MODE),","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/sink/client/ClickhouseSink.java#L95-L131","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nsink {\n  Clickhouse {\n    split_mode = true\n    table = \"my_merge_tree_table\"\n  }\n}\n// after\nsink {\n  Clickhouse {\n    split_mode = false\n    table = \"my_merge_tree_table\"\n  }\n}","handlingStrategy":"validation","validationCode":"// run before enabling split mode\nString engine = clickhouse.tableEngine(database, table);\nif (!\"Distributed\".equals(engine)) throw new IllegalArgumentException(\n    \"split_mode requires a Distributed table, got: \" + engine);","typeGuard":null,"tryCatchPattern":"try { createSinkWriter(config); } catch (ClickhouseConnectorException e) {\n  if (e.getCode().equals(CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT)) { /* disable split_mode or fix table */ }\n}","preventionTips":["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"],"tags":["clickhouse","config-validation","split-mode"],"backgroundTag":"invalid-config-value","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}