{"record":{"id":"45e704ed9bd3b913","repo":"apache/seatunnel","slug":"vitess-cdc-requires-explicit-schema-metadata-s","errorCode":null,"errorMessage":"Vitess CDC requires explicit schema metadata. '%s' must contain a schema block.","messagePattern":"Vitess CDC requires explicit schema metadata\\. '(.+?)' must contain a schema block\\.","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":155,"sourceCode":"        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)) {\n            throw new IllegalArgumentException(\n                    String.format(\n                            \"Vitess CDC requires explicit schema metadata. '%s' must contain a schema block.\",\n                            optionName));\n        }\n        validateRootSchemaDefinition((Map<String, Object>) schemaValue, optionName + \".schema\");\n    }\n","sourceCodeStart":137,"sourceCodeEnd":173,"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#L137-L173","documentation":"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.","triggerScenarios":"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.","commonSituations":"Schema block present but empty; misspelling 'columns' (e.g. 'column' or 'fields'); copying a schema block from another connector that uses different keys.","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"],"exampleFix":"// before\nschema { }\n// after\nschema { columns { id = \"bigint\" name = \"string\" } }","handlingStrategy":"validation","validationCode":"void checkSchema(Map<String,Object> schema) {\n    if (!schema.containsKey(\"columns\") && !schema.containsKey(\"metadata_table_id\")) {\n        throw new IllegalArgumentException(\"schema needs columns or metadata_table_id\");\n    }\n}","typeGuard":null,"tryCatchPattern":"try { factory.resolveCatalogTables(context); } catch (IllegalArgumentException e) { /* fix schema block keys */ }","preventionTips":["Use option keys exactly as documented (columns, metadata_table_id)","Start from the official Vitess CDC config template","Lint schema blocks for required keys"],"tags":["cdc","vitess","schema-validation"],"backgroundTag":"schema-validation-failed","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"}