{"record":{"id":"5198ea46d683545c","repo":"apache/seatunnel","slug":"vitess-cdc-requires-explicit-schema-metadata-throu","errorCode":null,"errorMessage":"Vitess CDC requires explicit schema metadata through either 'schema' or 'tables_configs'.","messagePattern":"Vitess CDC requires explicit schema metadata through either 'schema' or 'tables_configs'\\.","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":166,"sourceCode":"                \"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\n    private void validateSelectionOptions(TableSourceFactoryContext context) {\n        if (context.getOptions().getOptional(ConnectorCommonOptions.TABLE_NAMES).isPresent()\n                && context.getOptions()\n                        .getOptional(ConnectorCommonOptions.TABLE_PATTERN)\n                        .isPresent()) {\n            throw new IllegalArgumentException(\n                    \"Vitess CDC accepts either table-names or table-pattern, but not both.\");\n        }\n    }\n\n    private List<CatalogTable> filterDeclaredTables(","sourceCodeStart":148,"sourceCodeEnd":184,"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#L148-L184","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Ensure each tables_configs entry has a schema block (a map) with columns or metadata_table_id","Fix indentation/nesting so schema is a child map of the table config","Replace non-map schema values (strings, arrays) with a proper block"],"exampleFix":"// before\ntables_configs = [ { table-names = \"commerce.orders\", schema = \"orders_schema\" } ]\n// after\ntables_configs = [ { table-names = \"commerce.orders\", schema = { columns { id = \"bigint\" } } } ]","handlingStrategy":"type-guard","validationCode":"Object s = config.get(\"schema\");\nif (!(s instanceof Map)) {\n    throw new IllegalArgumentException(\"tables_configs[i].schema must be a map/block\");\n}","typeGuard":"boolean isValidSchemaBlock(Object v) { return v instanceof Map && !((Map<?,?>) v).isEmpty(); }","tryCatchPattern":"try { factory.resolveCatalogTables(context); } catch (IllegalArgumentException e) { /* fix schema nesting/type */ }","preventionTips":["Verify HOCON/YAML indentation keeps schema as a nested map","Never quote schema blocks into strings","Parse configs and assert schema value type before submit"],"tags":["cdc","vitess","schema-validation","type-mismatch"],"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"}