{"record":{"id":"7d58ca8e9d1d829e","repo":"apache/seatunnel","slug":"cluster-list-get-failed","errorCode":"CLUSTER_LIST_GET_FAILED","errorMessage":"Cannot get cluster shard list from clickhouse","messagePattern":"Cannot get cluster shard list from clickhouse","errorType":"error_code","errorClass":"ClickhouseConnectorException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/util/ClickhouseProxy.java","lineNumber":235,"sourceCode":"            response.records()\n                    .forEach(\n                            r -> {\n                                shardList.add(\n                                        new Shard(\n                                                r.getValue(0).asInteger(),\n                                                r.getValue(1).asInteger(),\n                                                r.getValue(2).asInteger(),\n                                                r.getValue(3).asString(),\n                                                r.getValue(4).asString(),\n                                                port,\n                                                database,\n                                                username,\n                                                password,\n                                                options));\n                            });\n            return shardList;\n        } catch (ClickHouseException e) {\n            throw new ClickhouseConnectorException(\n                    ClickhouseConnectorErrorCode.CLUSTER_LIST_GET_FAILED,\n                    \"Cannot get cluster shard list from clickhouse\",\n                    e);\n        }\n    }\n\n    /**\n     * Get ClickHouse table info.\n     *\n     * @param database database of the table.\n     * @param table table name of the table.\n     * @return clickhouse table info.\n     */\n    public ClickhouseTable getClickhouseTable(\n            ClickHouseRequest<?> clickhouseRequest, String database, String table) {\n        String sql =\n                String.format(\n                        \"select engine,create_table_query,engine_full,data_paths,sorting_key from system.tables where database = '%s' and name = '%s'\",","sourceCodeStart":217,"sourceCodeEnd":253,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/util/ClickhouseProxy.java#L217-L253","documentation":"ClickhouseProxy.getClusterShardList queries system.clusters (building a shard list with per-shard clients) and wraps ClickHouseException in a ClickhouseConnectorException with ClickhouseConnectorErrorCode.CLUSTER_LIST_GET_FAILED. It means the connector could not enumerate the shards/replicas of the configured cluster.","triggerScenarios":"Calling getClusterShardList (directly or via shardList/testWithShardRouterGetShardRight) when the cluster name in the Distributed table does not exist, or the system.clusters query fails (connection, auth, permissions).","commonSituations":"Configured cluster_name does not match any entry in system.clusters (often the default 'cluster' vs a custom name); user lacks privilege to read system.clusters; some shard hosts in system.clusters are unreachable from the client machine.","solutions":["Verify the cluster name: SELECT cluster, host_name FROM system.clusters; and fix cluster_name in config","Grant the user access to system.clusters if the query itself was denied","Ensure all shard/replica hosts listed in system.clusters are resolvable and reachable from the client","Use the Distributed table's engine_full to confirm which cluster it targets"],"exampleFix":"// before\nproxy.getClusterShardList(\"prod_cluster\"); // no such cluster\n// after\nproxy.getClusterShardList(\"my_distributed_cluster\"); // matches system.clusters","handlingStrategy":"validation","validationCode":"// confirm the cluster exists before building the shard list\nList<String> clusters = proxy.listDatabases(); // sanity connectivity\n// run: SELECT DISTINCT cluster FROM system.clusters and compare to configured cluster_name","typeGuard":"boolean clusterKnown = configuredClusters.stream()\n    .allMatch(c -> availableClustersFromSystemClusters.contains(c));","tryCatchPattern":"try {\n    List<Shard> shards = proxy.getClusterShardList(clusterName);\n} catch (ClickhouseConnectorException e) {\n    if (ClickhouseConnectorErrorCode.CLUSTER_LIST_GET_FAILED.equals(e.getSeaTunnelAPIErrorCode())) {\n        LOG.error(\"Cluster {} not found or system.clusters unreadable\", clusterName);\n    }\n    throw e;\n}","preventionTips":["Match cluster_name exactly against system.clusters (case-sensitive)","Ensure every shard/replica host is DNS-resolvable and reachable from the client","Grant access to system.clusters for the job user","Pin credentials consistent across all shards"],"tags":["clickhouse","cluster","metadata"],"backgroundTag":"resource-not-found","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"}