{"record":{"id":"81000e3d627a8486","repo":"apache/seatunnel","slug":"vitess-cdc-requires-explicit-columns-or-metadata-t","errorCode":null,"errorMessage":"Vitess CDC requires explicit columns or metadata_table_id in '%s' so table schemas stay deterministic.","messagePattern":"Vitess CDC requires explicit columns or metadata_table_id in '(.+?)' so table schemas stay deterministic\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/VitessSourceFactory.java","lineNumber":147,"sourceCode":"        Optional<Map<String, Object>> singleSchema =\n                context.getOptions().getOptional(ConnectorCommonOptions.SCHEMA);\n        Optional<List<Map<String, Object>>> tableConfigs =\n                context.getOptions().getOptional(ConnectorCommonOptions.TABLE_CONFIGS);\n        if (singleSchema.isPresent()) {\n            validateRootSchemaDefinition(singleSchema.get(), \"schema\");\n            return;\n        }\n        if (tableConfigs.isPresent()) {\n            List<Map<String, Object>> configs = tableConfigs.get();\n            if (configs.isEmpty()) {\n                throw new IllegalArgumentException(\"tables_configs can not be empty.\");\n            }\n            for (int index = 0; index < configs.size(); index++) {\n                validateSchemaDefinition(configs.get(index), \"tables_configs[\" + index + \"]\");\n            }\n            return;\n        }\n        throw new IllegalArgumentException(\n                \"Vitess CDC requires explicit schema metadata through either 'schema' or 'tables_configs'.\");\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    private void validateRootSchemaDefinition(Map<String, Object> schema, String optionName) {\n        if (!schema.containsKey(ColumnOptions.COLUMNS.key())\n                && !schema.containsKey(ColumnOptions.METADATA_TABLE_ID.key())) {\n            throw new IllegalArgumentException(\n                    String.format(\n                            \"Vitess CDC requires explicit columns or metadata_table_id in '%s' so table schemas stay deterministic.\",\n                            optionName));\n        }\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    private void validateSchemaDefinition(Map<String, Object> config, String optionName) {\n        Object schemaValue = config.get(ConnectorCommonOptions.SCHEMA.key());\n        if (!(schemaValue instanceof Map)) {","sourceCodeStart":129,"sourceCodeEnd":165,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/source/VitessSourceFactory.java#L129-L165","documentation":"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.","triggerScenarios":"Calling VitessSourceFactory.resolveCatalogTables when schema is absent AND tables_configs is absent (tableConfigs.isPresent() is false).","commonSituations":"Minimal source configs copied from non-CDC examples; older configs written before schema metadata became mandatory; deleting a schema block while refactoring.","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"],"exampleFix":"// before\nVitess { keyspace = \"commerce\" tables = [\"commerce.orders\"] }\n// after\nVitess {\n  keyspace = \"commerce\"\n  tables = [\"commerce.orders\"]\n  schema { columns { id = \"bigint\" order_no = \"string\" } }\n}","handlingStrategy":"validation","validationCode":"if (!options.containsKey(SCHEMA) && !options.containsKey(TABLES_CONFIGS)) {\n    throw new IllegalArgumentException(\"Provide 'schema' or 'tables_configs' for Vitess CDC\");\n}","typeGuard":null,"tryCatchPattern":"try { factory.resolveCatalogTables(context); } catch (IllegalArgumentException e) { /* add schema metadata block */ }","preventionTips":["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"],"tags":["cdc","vitess","missing-schema"],"backgroundTag":"missing-required-config-field","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}