apache/seatunnel · error · IllegalArgumentException

Vitess CDC requires explicit columns or metadata_table_id in

Error message

Vitess CDC requires explicit columns or metadata_table_id in '%s' so table schemas stay deterministic.

What it means

Fallback error of validateSchemaMetadataContract: thrown when neither the 'schema' option nor 'tables_configs' is provided. Vitess CDC requires explicit schema metadata (columns or metadata_table_id) so table schemas are deterministic instead of inferred.

Solutions

Add a top-level 'schema' block containing columns (and optionally metadata_table_id)
Add a 'tables_configs' list with per-table schema blocks
Regenerate the config from the current Vitess CDC documentation template

Example fix

// before
Vitess { keyspace = "commerce" tables = ["commerce.orders"] }
// after
Vitess {
  keyspace = "commerce"
  tables = ["commerce.orders"]
  schema { columns { id = "bigint" order_no = "string" } }
}

Defensive patterns

Strategy: validation

Validate before calling

if (!options.containsKey(SCHEMA) && !options.containsKey(TABLES_CONFIGS)) {
    throw new IllegalArgumentException("Provide 'schema' or 'tables_configs' for Vitess CDC");
}

Try / catch

try { factory.resolveCatalogTables(context); } catch (IllegalArgumentException e) { /* add schema metadata block */ }

Prevention

Always ship a schema block in Vitess CDC job configs
Update old job templates that predate mandatory schema metadata
Review connector docs when migrating from inferred-schema versions

When it happens

Trigger: Calling VitessSourceFactory.resolveCatalogTables when schema is absent AND tables_configs is absent (tableConfigs.isPresent() is false).

Common situations: Minimal source configs copied from non-CDC examples; older configs written before schema metadata became mandatory; deleting a schema block while refactoring.

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

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

Appendix: source

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

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

    @SuppressWarnings("unchecked")
    private void validateSchemaDefinition(Map<String, Object> config, String optionName) {
        Object schemaValue = config.get(ConnectorCommonOptions.SCHEMA.key());
        if (!(schemaValue instanceof Map)) {

View on GitHub (pinned to cf67b549a7)