apache/seatunnel · error · ClickhouseConnectorException

LIST_TABLES_FAILED

LIST_TABLES_FAILED

Error message

Cannot list tables from clickhouse

What it means

ClickhouseProxy.listTable runs a query listing tables for a database from system.tables and wraps ClickHouseException into a ClickhouseConnectorException with LIST_TABLES_FAILED. It means the connector could not list tables in the requested database.

Source

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

                    .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);
        }
    }

    public void executeSql(String sql) {
        try {
            clickhouseRequest
                    .write()
                    .format(ClickHouseFormat.RowBinaryWithNamesAndTypes)
                    .query(sql)
                    .execute()
                    .get();
        } catch (InterruptedException | ExecutionException e) {
            throw new RuntimeException(e);
        }
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Confirm the database exists: SHOW DATABASES; and fix the name
2. Grant the user privilege to read that database's catalog entries
3. Check connectivity/credentials and retry
4. Inspect the wrapped ClickHouseException for the precise server-side reason

Example fix

// before
proxy.listTable("proddb "); // trailing space in database name
// after
proxy.listTable("proddb");

List<String> dbs = proxy.listDatabases();
if (!dbs.contains(database)) {
    throw new IllegalArgumentException("Unknown database: " + database);
}

try {
    return proxy.listTable(database);
} catch (ClickhouseConnectorException e) {
    LOG.error("Table listing failed for db {}", database, e);
    throw e;
}

When it happens

Trigger: Calling listTable when the underlying system.tables listing query fails — connection failure, bad credentials, unknown/misspelled database causing an error, or permission denial.

Common situations: Database name typo in config; user restricted to specific databases; transient network issues while browsing the catalog in tooling built on this proxy.

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_DATABASES_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/13120f6a56b1e836. Report an issue: GitHub.