apache/seatunnel · error · IllegalArgumentException

tables_configs can not be empty.

Error message

tables_configs can not be empty.

What it means

Thrown in validateSchemaMetadataContract when the tables_configs option is provided but the list is empty. The factory requires schema metadata for every table; an empty list is treated as a configuration error rather than silently falling back.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/VitessSourceFactory.java:140

    private List<CatalogTable> resolveCatalogTables(TableSourceFactoryContext context) {
        validateSchemaMetadataContract(context);
        validateSelectionOptions(context);
        return filterDeclaredTables(context, discoverTableSchemas(context));
    }

    private void validateSchemaMetadataContract(TableSourceFactoryContext context) {
        Optional<Map<String, Object>> singleSchema =
                context.getOptions().getOptional(ConnectorCommonOptions.SCHEMA);
        Optional<List<Map<String, Object>>> tableConfigs =
                context.getOptions().getOptional(ConnectorCommonOptions.TABLE_CONFIGS);
        if (singleSchema.isPresent()) {
            validateRootSchemaDefinition(singleSchema.get(), "schema");
            return;
        }
        if (tableConfigs.isPresent()) {
            List<Map<String, Object>> configs = tableConfigs.get();
            if (configs.isEmpty()) {
                throw new IllegalArgumentException("tables_configs can not be empty.");
            }
            for (int index = 0; index < configs.size(); index++) {
                validateSchemaDefinition(configs.get(index), "tables_configs[" + index + "]");
            }
            return;
        }
        throw new IllegalArgumentException(
                "Vitess CDC requires explicit schema metadata through either 'schema' or 'tables_configs'.");
    }

    @SuppressWarnings("unchecked")
    private void validateRootSchemaDefinition(Map<String, Object> schema, String optionName) {
        if (!schema.containsKey(ColumnOptions.COLUMNS.key())
                && !schema.containsKey(ColumnOptions.METADATA_TABLE_ID.key())) {
            throw new IllegalArgumentException(
                    String.format(
                            "Vitess CDC requires explicit columns or metadata_table_id in '%s' so table schemas stay deterministic.",
                            optionName));

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add at least one table config entry with a schema block to tables_configs
2. Remove the tables_configs key entirely and use the 'schema' option instead
3. Fix the templating/pipeline that produced the empty list

Example fix

// before
tables_configs = []
// after
tables_configs = [
  { table-names = "commerce.orders"
    schema { columns { id = bigint } } }
]

List<Map<String,Object>> configs = options.get(TABLES_CONFIGS);
if (configs != null && configs.isEmpty()) {
    throw new IllegalArgumentException("tables_configs must not be empty");
}

try { factory.resolveCatalogTables(context); } catch (IllegalArgumentException e) { /* populate tables_configs or drop the key */ }

When it happens

Trigger: Calling VitessSourceFactory.resolveCatalogTables with tables_configs configured as an empty array/map list (configs.isEmpty() is true).

Common situations: Template variables that expanded to an empty list; deleting all entries from tables_configs while leaving the key; automated config generation emitting '[]'.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Vitess CDC requires resolved catalog tables for deterministi
• Vitess CDC captures one keyspace per source. Table '%s' does
• Invalid value for option '" + optionKey + "'. " + e.getMessa
• Unknown schema change event type '" + canonicalName + "'. Va
• '${SourceOptions.STARTUP_SPECIFIC_OFFSET_FILE.key()}' and '$

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