{"record":{"id":"8f579a43e423ca90","repo":"apache/seatunnel","slug":"clickhouse-shard-key-not-found","errorCode":"CLICKHOUSE_SHARD_KEY_NOT_FOUND","errorMessage":"Shard key  not found in table ","messagePattern":"Shard key  not found in table ","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/ShardRouter.java","lineNumber":69,"sourceCode":"    private final TreeMap<Integer, Shard> shards;\n    private final String shardKey;\n    private final String shardKeyType;\n    @Getter private final String sortingKey;\n    private final boolean splitMode;\n\n    private static final XXHash64 HASH_INSTANCE = XXHashFactory.fastestInstance().hash64();\n    private final ThreadLocalRandom threadLocalRandom = ThreadLocalRandom.current();\n\n    public ShardRouter(ClickhouseProxy proxy, ShardMetadata shardMetadata) {\n        this.shards = new TreeMap<>();\n        this.shardKey = shardMetadata.getShardKey();\n        this.shardKeyType = shardMetadata.getShardKeyType();\n        this.sortingKey = shardMetadata.getSortingKey();\n        this.splitMode = shardMetadata.isSplitMode();\n        this.table = shardMetadata.getTable();\n        this.tableEngine = shardMetadata.getTableEngine();\n        if (StringUtils.isNotEmpty(shardKey) && StringUtils.isEmpty(shardKeyType)) {\n            throw new ClickhouseConnectorException(\n                    ClickhouseConnectorErrorCode.SHARD_KEY_NOT_FOUND,\n                    \"Shard key \" + shardKey + \" not found in table \" + table);\n        }\n        ClickHouseRequest<?> connection = proxy.getClickhouseConnection();\n        if (splitMode) {\n            DistributedEngine localTable =\n                    proxy.getClickhouseDistributedTable(\n                            connection, shardMetadata.getDatabase(), table);\n            this.shardTable = localTable.getTable();\n            this.shardTableEngine = localTable.getTableEngine();\n            List<Shard> shardList =\n                    proxy.getClusterShardList(\n                            connection,\n                            localTable.getClusterName(),\n                            localTable.getDatabase(),\n                            shardMetadata.getDefaultShard().getNode().getPort(),\n                            shardMetadata.getUsername(),\n                            shardMetadata.getPassword(),","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/sink/client/ShardRouter.java#L51-L87","documentation":"The configured sharding_key does not exist in the target ClickHouse table's column metadata, so the connector cannot determine its type for shard routing. ShardRouter validates that a non-empty shard key resolves to a known shard key type and fails with CLICKHOUSE_SHARD_KEY_NOT_FOUND otherwise.","triggerScenarios":"Configuring sharding_key = \"some_col\" where some_col is not a column of the ClickHouse table (typo, wrong case, or key defined only on an upstream schema); raised in the ShardRouter constructor.","commonSituations":"Copy-pasted config from another table, column renamed/dropped in ClickHouse, case-sensitivity mismatch, or using an expression (e.g. rand(), cityHash64(...)) that is not a plain column when the metadata lookup expects one.","solutions":["Set sharding_key to an exact existing column name of the table (match case)","Remove sharding_key to let ClickHouse route with its default sharding expression","If using a shard expression like rand()/hash, verify what the table's actual sharding column is and reference that column"],"exampleFix":"// before\nsharding_key = \"usr_id\"\n// after\nsharding_key = \"user_id\"","handlingStrategy":"validation","validationCode":"Set<String> cols = clickhouse.tableColumns(database, table);\nString shardKey = config.getOptional(SHARDING_KEY).orElse(null);\nif (shardKey != null && !cols.contains(shardKey))\n  throw new IllegalArgumentException(\"sharding_key not a column: \" + shardKey);","typeGuard":null,"tryCatchPattern":"try { createSinkWriter(config); } catch (ClickhouseConnectorException e) {\n  if (e.getCode().equals(ClickhouseConnectorErrorCode.SHARD_KEY_NOT_FOUND)) {\n    /* correct or remove sharding_key */ }\n}","preventionTips":["Match the sharding_key string exactly (including case) to a table column","Re-check sharding_key after any table DDL (rename/drop of columns)","Use the table's real sharding column, not an arbitrary expression"],"tags":["clickhouse","sharding","config-validation","column-not-found"],"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"}