apache/seatunnel · error · ClickhouseConnectorException

LIST_DATABASES_FAILED

LIST_DATABASES_FAILED

Error message

Cannot list databases from clickhouse

What it means

ClickhouseProxy.listDatabases runs 'select distinct database from system.tables' and wraps ClickHouseException into a ClickhouseConnectorException with SeaTunnelAPIErrorCode.LIST_DATABASES_FAILED. It means the connector could not enumerate databases from the server.

Source

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

                        "select count(1) from system.tables where database = '%s' and name = '%s'",
                        database, table);
        try (ClickHouseResponse response = clickhouseRequest.query(sql).executeAndWait()) {
            return response.firstRecord().getValue(0).asInteger() > 0;
        } catch (ClickHouseException e) {
            throw new ClickhouseConnectorException(
                    SeaTunnelAPIErrorCode.TABLE_NOT_EXISTED, "Cannot get table from clickhouse", e);
        }
    }

    public List<String> listDatabases() {
        String sql = "select distinct database from system.tables";
        try (ClickHouseResponse response = clickhouseRequest.query(sql).executeAndWait()) {
            Iterable<ClickHouseRecord> records = response.records();
            return StreamSupport.stream(records.spliterator(), false)
                    .map(r -> r.getValue(0).asString())
                    .collect(Collectors.toList());
        } catch (ClickHouseException e) {
            throw new ClickhouseConnectorException(
                    SeaTunnelAPIErrorCode.LIST_DATABASES_FAILED,
                    "Cannot list databases from clickhouse",
                    e);
        }
    }

    public List<String> listTable(String database) {
        String sql = "SELECT name FROM system.tables WHERE database = '" + database + "'";
        try (ClickHouseResponse response = clickhouseRequest.query(sql).executeAndWait()) {
            Iterable<ClickHouseRecord> records = response.records();
            return StreamSupport.stream(records.spliterator(), false)
                    .map(r -> r.getValue(0).asString())
                    .collect(Collectors.toList());
        } catch (ClickHouseException e) {
            throw new ClickhouseConnectorException(
                    SeaTunnelAPIErrorCode.LIST_TABLES_FAILED,
                    "Cannot list tables from clickhouse",
                    e);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Verify connection parameters and test with clickhouse-client
2. Grant SHOW DATABASES / access to system.tables for the user
3. Retry after confirming the ClickHouse server is healthy
4. Check proxy/firewall rules if connections to port 8123/9000 are blocked

// connectivity probe
proxy.getClickHouseColumns("system.one"); // throws early if the server is unreachable

try {
    return proxy.listDatabases();
} catch (ClickhouseConnectorException e) {
    if (SeaTunnelAPIErrorCode.LIST_DATABASES_FAILED.equals(e.getSeaTunnelAPIErrorCode())) {
        return retryWithBackoff(3, () -> proxy.listDatabases());
    }
    throw e;
}

When it happens

Trigger: Calling listDatabases when the query against system.tables fails due to connection errors, authentication failure, or insufficient privileges.

Common situations: Wrong host/port/credentials in config; user denied access to system tables; ClickHouse server restarting during catalog exploration (e.g. while building table/file source configs).

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• Failed getting table %s
• LIST_TABLES_FAILED
• Truncate table failed
• Failed EXECUTE SQL in catalog %s
• Unsupported action type:

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