apache/seatunnel · error · IllegalArgumentException

Vitess CDC requires explicit schema metadata.

Error message

Vitess CDC requires explicit schema metadata. '%s' must contain a schema block.

What it means

Thrown by validateRootSchemaDefinition when a schema block (root 'schema' or a per-table schema inside tables_configs) contains neither 'columns' nor 'metadata_table_id'. The connector refuses ambiguous schemas so results stay deterministic.

Solutions

Add a 'columns' entry to the schema block listing each column and its SeaTunnel type
Add 'metadata_table_id' to the schema block if relying on Vitess table metadata
Fix the misspelled option key

Example fix

// before
schema { }
// after
schema { columns { id = "bigint" name = "string" } }

Defensive patterns

Strategy: validation

Validate before calling

void checkSchema(Map<String,Object> schema) {
    if (!schema.containsKey("columns") && !schema.containsKey("metadata_table_id")) {
        throw new IllegalArgumentException("schema needs columns or metadata_table_id");
    }
}

Try / catch

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

Prevention

Use option keys exactly as documented (columns, metadata_table_id)
Start from the official Vitess CDC config template
Lint schema blocks for required keys

When it happens

Trigger: Passing a schema map that lacks ColumnOptions.COLUMNS.key() and ColumnOptions.METADATA_TABLE_ID.key(), via the 'schema' option or via tables_configs[i].schema.

Common situations: Schema block present but empty; misspelling 'columns' (e.g. 'column' or 'fields'); copying a schema block from another connector that uses different keys.

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/45e704ed9bd3b913. 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:155

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

View on GitHub (pinned to cf67b549a7)