apache/seatunnel · error · ClickhouseConnectorException

TABLE_SCHEMA_GET_FAILED

TABLE_SCHEMA_GET_FAILED

Error message

Cannot get table schema from clickhouse

What it means

ClickhouseProxy.getClickhouseTableSchema issues a DESCRIBE-style query against system.columns and wraps any ClickHouseException into a ClickhouseConnectorException with CommonErrorCodeDeprecated.TABLE_SCHEMA_GET_FAILED. It means the connector could not read the column name/type pairs for the requested table.

Source

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

    public Map<String, String> getClickhouseTableSchema(String table) {
        ClickHouseRequest<?> request = getClickhouseConnection();
        return getClickhouseTableSchema(request, table);
    }

    public Map<String, String> getClickhouseTableSchema(
            ClickHouseRequest<?> request, String table) {
        String sql = "desc " + table;
        Map<String, String> schema = new LinkedHashMap<>();
        try (ClickHouseResponse response = request.query(sql).executeAndWait()) {
            response.records()
                    .forEach(
                            r -> {
                                if (!"MATERIALIZED".equals(r.getValue(2).asString())) {
                                    schema.put(r.getValue(0).asString(), r.getValue(1).asString());
                                }
                            });
        } catch (ClickHouseException e) {
            throw new ClickhouseConnectorException(
                    CommonErrorCodeDeprecated.TABLE_SCHEMA_GET_FAILED,
                    "Cannot get table schema from clickhouse",
                    e);
        }
        return schema;
    }

    public List<ClickHouseColumn> getClickHouseColumns(String table) {
        String sql = "SELECT * FROM " + table + " WHERE 1 = 0";
        try (ClickHouseResponse response = this.clickhouseRequest.query(sql).executeAndWait()) {
            return response.getColumns();

        } catch (ClickHouseException e) {
            throw new ClickhouseConnectorException(
                    CommonErrorCodeDeprecated.TABLE_SCHEMA_GET_FAILED,
                    "Cannot get table schema from clickhouse",
                    e);
        }

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Confirm the table exists: SELECT name FROM system.tables WHERE database='<db>' AND name='<table>';
  2. Validate database and table names in the connector config (quote identifiers containing dots)
  3. Grant the ClickHouse user SELECT privilege on the table and system.columns
  4. Check network connectivity and credentials in the ClickHouse URL/options
  5. Retry if the failure was a transient ClickHouseException (server restart, timeout)

Example fix

// before
Map<String,String> schema = proxy.getClickhouseTableSchema(request, "events"); // table in db 'prod', not default
// after
Map<String,String> schema = proxy.getClickhouseTableSchema(request, "prod.events"); // fully qualified name
Defensive patterns

Strategy: validation

Validate before calling

if (!proxy.tableExists(request, database, table)) {
    throw new IllegalArgumentException(database + "." + table + " does not exist");
}

Try / catch

try {
    Map<String,String> schema = proxy.getClickhouseTableSchema(request, table);
} catch (ClickhouseConnectorException e) {
    // inspect cause ClickHouseException for auth/connectivity; retry once on transient errors
    throw new RuntimeException("Schema read failed: " + e.getMessage(), e);
}

Prevention

When it happens

Trigger: Calling getClickhouseTableSchema (directly or via getClickhouseTable) when the table does not exist, the database name is wrong, or the query fails due to connection/auth/timeout errors surfaced as ClickHouseException.

Common situations: Typo in table name in config; user lacks SELECT privilege on the table; ClickHouse server unreachable or restarted mid-query; materialized views referenced without permissions.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

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