apache/seatunnel · error · ClickhouseConnectorException

CLUSTER_LIST_GET_FAILED

CLUSTER_LIST_GET_FAILED

Error message

Cannot get cluster shard list from clickhouse

What it means

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.

Source

Thrown at seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/util/ClickhouseProxy.java:235

            response.records()
                    .forEach(
                            r -> {
                                shardList.add(
                                        new Shard(
                                                r.getValue(0).asInteger(),
                                                r.getValue(1).asInteger(),
                                                r.getValue(2).asInteger(),
                                                r.getValue(3).asString(),
                                                r.getValue(4).asString(),
                                                port,
                                                database,
                                                username,
                                                password,
                                                options));
                            });
            return shardList;
        } catch (ClickHouseException e) {
            throw new ClickhouseConnectorException(
                    ClickhouseConnectorErrorCode.CLUSTER_LIST_GET_FAILED,
                    "Cannot get cluster shard list from clickhouse",
                    e);
        }
    }

    /**
     * Get ClickHouse table info.
     *
     * @param database database of the table.
     * @param table table name of the table.
     * @return clickhouse table info.
     */
    public ClickhouseTable getClickhouseTable(
            ClickHouseRequest<?> clickhouseRequest, String database, String table) {
        String sql =
                String.format(
                        "select engine,create_table_query,engine_full,data_paths,sorting_key from system.tables where database = '%s' and name = '%s'",

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify the cluster name: SELECT cluster, host_name FROM system.clusters; and fix cluster_name in config
2. Grant the user access to system.clusters if the query itself was denied
3. Ensure all shard/replica hosts listed in system.clusters are resolvable and reachable from the client
4. Use the Distributed table's engine_full to confirm which cluster it targets

Example fix

// before
proxy.getClusterShardList("prod_cluster"); // no such cluster
// after
proxy.getClusterShardList("my_distributed_cluster"); // matches system.clusters

// confirm the cluster exists before building the shard list
List<String> clusters = proxy.listDatabases(); // sanity connectivity
// run: SELECT DISTINCT cluster FROM system.clusters and compare to configured cluster_name

boolean clusterKnown = configuredClusters.stream()
    .allMatch(c -> availableClustersFromSystemClusters.contains(c));

try {
    List<Shard> shards = proxy.getClusterShardList(clusterName);
} catch (ClickhouseConnectorException e) {
    if (ClickhouseConnectorErrorCode.CLUSTER_LIST_GET_FAILED.equals(e.getSeaTunnelAPIErrorCode())) {
        LOG.error("Cluster {} not found or system.clusters unreadable", clusterName);
    }
    throw e;
}

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Failed getting table %s
• TABLE_NOT_EXISTED
• TABLE_SCHEMA_GET_FAILED
• LIST_DATABASES_FAILED
• LIST_TABLES_FAILED

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