apache/seatunnel · error · ClickhouseConnectorException

CLICKHOUSE_GET_TABLE_LIST_CONFIG_ERROR

CLICKHOUSE_GET_TABLE_LIST_CONFIG_ERROR

Error message

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

What it means

ClickhouseTableConfig.of(ReadonlyConfig) builds the per-table configuration list for a ClickHouse source. After building tableList — from the 'table_list' option or a single table_path/sql — it validates the list is non-empty; otherwise it throws ClickhouseConnectorException with code GET_TABLE_LIST_CONFIG_ERROR carrying the plugin name/type. It means the source config yielded no table entries at all.

Source

Thrown at seatunnel-connectors-v2/connector-clickhouse/src/main/java/org/apache/seatunnel/connectors/seatunnel/clickhouse/config/ClickhouseTableConfig.java:95

        List<ClickhouseTableConfig> tableList;
        if (readonlyConfig.getOptional(TABLE_LIST).isPresent()) {
            tableList = readonlyConfig.get(TABLE_LIST);
        } else {
            ClickhouseTableConfig tableConfig =
                    ClickhouseTableConfig.builder()
                            .tablePath(readonlyConfig.get(TABLE_PATH))
                            .sql(readonlyConfig.get(SQL))
                            .filterQuery(readonlyConfig.get(CLICKHOUSE_FILTER_QUERY))
                            .partitionList(readonlyConfig.get(CLICKHOUSE_PARTITION_LIST))
                            .batchSize(readonlyConfig.get(CLICKHOUSE_BATCH_SIZE))
                            .splitSize(readonlyConfig.get(CLICKHOUSE_SPLIT_SIZE))
                            .build();

            tableList = Collections.singletonList(tableConfig);
        }

        if (tableList == null || tableList.isEmpty()) {
            throw new ClickhouseConnectorException(
                    ClickhouseConnectorErrorCode.GET_TABLE_LIST_CONFIG_ERROR,
                    String.format(
                            "PluginName: %s, PluginType: %s, Message: %s",
                            "Clickhouse", PluginType.SOURCE, "Get table list config error."));
        }

        for (ClickhouseTableConfig tableConfig : tableList) {
            if (StringUtils.isEmpty(tableConfig.getTablePath())
                    && StringUtils.isEmpty(tableConfig.getSql())) {
                throw new IllegalArgumentException(
                        "`table_path` and `sql` parameter cannot be both empty.");
            }

            if (tableConfig.getBatchSize() <= 0) {
                tableConfig.setBatchSize(CLICKHOUSE_BATCH_SIZE.defaultValue());
            }

            if (tableConfig.getSplitSize() <= 0) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add a valid 'table_path' (e.g. "database_name.table_name") to the ClickHouse source config.
2. Alternatively provide a 'sql' query or a non-empty 'table_list' array of table entries.
3. Verify option key spellings against ClickhouseSourceOptions and check the connector's full option list.
4. Enable debug logging of the resolved ReadonlyConfig to confirm which options the connector actually sees.

Example fix

// before
source {
  Clickhouse {
    url = "jdbc:clickhouse://localhost:8123"
  }
}
// after
source {
  Clickhouse {
    url = "jdbc:clickhouse://localhost:8123"
    table_path = "default.my_table"
  }
}

if (!config.containsKey("table_list") && !config.containsKey("table_path") && !config.containsKey("sql")) {
    throw new IllegalArgumentException("Clickhouse source requires 'table_path', 'sql', or a non-empty 'table_list'");
}

try { tableConfigs = ClickhouseTableConfig.of(readonlyConfig); } catch (ClickhouseConnectorException e) { if (ClickhouseConnectorErrorCode.GET_TABLE_LIST_CONFIG_ERROR.equals(e.getSeaTunnelErrorCode())) { log.error("Clickhouse source config has no tables: check table_path/sql/table_list"); } throw e; }

When it happens

Trigger: Creating a ClickhouseTableConfig from a ReadonlyConfig that contains neither a 'table_list' array nor a directly usable 'table_path'/'sql' entry, so the constructed tableList ends up null or empty.

Common situations: Omitting table_path (and database/table) from the source config; providing an empty table_list: []; misspelling the option key (e.g. 'tablepath' or 'tablePaths') so it is ignored; hand-editing configs and deleting required fields.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• Option 'field_delimiter' cannot be empty
• Option 'batch_size' must be between 1 and 32
• Option 'visibility_timeout_seconds' must be between 1 and 60
• Option 'poll_interval_ms' must be greater than zero
• Option 'max_in_flight_messages' must be greater than or equa

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