apache/seatunnel · error · ClickhouseConnectorException

SEA-TUNNEL-API-01

SEA-TUNNEL-API-01

Error message

PluginName: %s, PluginType: %s, Message: %s

What it means

ClickhouseSourceFactory.createSource() throws CONFIG_VALIDATION_FAILED (SEA-TUNNEL-API-01) wrapping a ClickHouseException raised while introspecting the configured table(s). It packages the ClickHouse driver error message into the standard plugin/pluginType/message format. Means the job config referenced a ClickHouse table that the server rejected or failed to query during source setup.

Source

Thrown at seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/source/ClickhouseSourceFactory.java:213

                                .tablePath(tablePath)
                                .clickhouseTable(clickhouseTable)
                                .originQuery(sql)
                                .filterQuery(tableConfig.getFilterQuery())
                                .splitSize(tableConfig.getSplitSize())
                                .batchSize(tableConfig.getBatchSize())
                                .partitionList(tableConfig.getPartitionList())
                                .isSqlStrategyRead(tableConfig.isSqlStrategyRead())
                                .isComplexSql(isComplexSql)
                                .catalogTable(catalogTable)
                                .build();

                clickhouseSourceTables.put(tablePath, clickhouseSourceTable);
                // The database may be different for each tableConfig
                // so create a separate nodes for each tablePath
                nodesMap.put(tablePath, nodes);

            } catch (ClickHouseException e) {
                throw new ClickhouseConnectorException(
                        SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED,
                        String.format(
                                "PluginName: %s, PluginType: %s, Message: %s",
                                factoryIdentifier(), PluginType.SOURCE, e.getMessage()));
            }
        }

        return () ->
                (SeaTunnelSource<T, SplitT, StateT>)
                        new ClickhouseSource(
                                nodesMap, clickhouseSourceTables, clickhouseSourceConfig);
    }

    private String modifySQLToLimit1(String sql) {
        return String.format("SELECT * FROM (%s) s LIMIT 1", sql);
    }

    private String generateQuerySql(String sql, String database, String table) {

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Read the inner 'Message' — it contains the actual ClickHouseException text identifying the real problem
  2. Verify database.table names in the config exist on the server: SHOW TABLES FROM <db>
  3. Test the configured username/password/URL with clickhouse-client using the same credentials
  4. Check GRANTS for the configured user on the target tables
  5. Verify the configured host:port list is reachable from the SeaTunnel worker

Example fix

// before
schema = {
  table = "default.non_existent_table"
}
// after: use an existing table
schema = {
  table = "default.events"
}
Defensive patterns

Strategy: validation

Validate before calling

# validate table access before submitting the job
clickhouse-client --host "$HOST" --user "$USER" --password "$PASSWORD" \
  --query "EXISTS TABLE ${DATABASE}.${TABLE}"
clickhouse-client ... --query "SELECT 1 FROM ${DATABASE}.${TABLE} LIMIT 1"  # tests grants too

Try / catch

try {
    Source<?, ?, ?> source = factory.createSource(config);
} catch (ClickhouseConnectorException e) {
    if (e.getErrorCode() == SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED) {
        // parse the inner driver message after 'Message: ' for the real ClickHouse error
        log.error("ClickHouse rejected the source table config: {}", e.getMessage());
    }
    throw e;
}

Prevention

When it happens

Trigger: During createSource (called via tableSource), a ClickHouseException is thrown by driver calls that read table metadata (e.g. DESCRIBE / system.tables query for each tablePath) — table missing, bad credentials, unreachable node, or malformed database/table name.

Common situations: Typo in database or table name in the config, user lacking privileges on the table, cluster/host list misconfigured, ClickHouse server down, or special characters in identifiers that the driver rejects.

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/ab668a3c7422ff9b. Report an issue: GitHub.