apache/seatunnel · error · IllegalArgumentException

Vitess CDC requires explicit schema metadata through either…

Error message

Vitess CDC requires explicit schema metadata through either 'schema' or 'tables_configs'.

What it means

Thrown by validateSchemaDefinition when an entry in tables_configs does not contain a parseable 'schema' block (the schema value is missing or is not a Map). Each per-table config must carry explicit schema metadata.

Solutions

1. Ensure each tables_configs entry has a schema block (a map) with columns or metadata_table_id
2. Fix indentation/nesting so schema is a child map of the table config
3. Replace non-map schema values (strings, arrays) with a proper block

Example fix

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

Object s = config.get("schema");
if (!(s instanceof Map)) {
    throw new IllegalArgumentException("tables_configs[i].schema must be a map/block");
}

boolean isValidSchemaBlock(Object v) { return v instanceof Map && !((Map<?,?>) v).isEmpty(); }

try { factory.resolveCatalogTables(context); } catch (IllegalArgumentException e) { /* fix schema nesting/type */ }

When it happens

Trigger: tables_configs[i] either has no key equal to ConnectorCommonOptions.SCHEMA.key() or its value is not a Map (e.g. a string, list, or nested wrong type).

Common situations: Writing 'schema = "..."' as a string instead of a block/map; YAML/HOCON indentation errors that flatten the schema block; copying configs where schema sits at the wrong nesting level.

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

• Vitess CDC requires explicit schema metadata.
• Failed to build the split data read statement.
• startup.specific-offset.vgtid is required when…
• tables_configs can not be empty.
• Type mismatch for column

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/5198ea46d683545c. 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:166

                "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)) {
            throw new IllegalArgumentException(
                    String.format(
                            "Vitess CDC requires explicit schema metadata. '%s' must contain a schema block.",
                            optionName));
        }
        validateRootSchemaDefinition((Map<String, Object>) schemaValue, optionName + ".schema");
    }

    private void validateSelectionOptions(TableSourceFactoryContext context) {
        if (context.getOptions().getOptional(ConnectorCommonOptions.TABLE_NAMES).isPresent()
                && context.getOptions()
                        .getOptional(ConnectorCommonOptions.TABLE_PATTERN)
                        .isPresent()) {
            throw new IllegalArgumentException(
                    "Vitess CDC accepts either table-names or table-pattern, but not both.");
        }
    }

    private List<CatalogTable> filterDeclaredTables(

View on GitHub (pinned to cf67b549a7)