{"record":{"id":"0ddd473f5b927b93","repo":"apache/seatunnel","slug":"startup-specific-offset-vgtid-is-required-when-sta","errorCode":null,"errorMessage":"startup.specific-offset.vgtid is required when startup.mode=specific.","messagePattern":"startup\\.specific-offset\\.vgtid is required when startup\\.mode=specific\\.","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/config/VitessSourceConfig.java","lineNumber":116,"sourceCode":"                throw new IllegalArgumentException(\n                        String.format(\n                                \"Vitess CDC captures one keyspace per source. Table '%s' does not belong to keyspace '%s'.\",\n                                catalogTable.getTablePath(), keyspace));\n            }\n            if (catalogTable.getTablePath().getSchemaName() != null) {\n                throw new IllegalArgumentException(\n                        String.format(\n                                \"Vitess CDC does not support schema-qualified table paths. Table '%s' contains an unexpected schema component.\",\n                                catalogTable.getTablePath()));\n            }\n        }\n\n        StartupMode startupMode = options.get(VitessSourceOptions.STARTUP_MODE);\n        String specificVgtid =\n                options.getOptional(VitessSourceOptions.STARTUP_SPECIFIC_OFFSET_VGTID).orElse(null);\n        if (startupMode == StartupMode.SPECIFIC) {\n            if (specificVgtid == null) {\n                throw new IllegalArgumentException(\n                        \"startup.specific-offset.vgtid is required when startup.mode=specific.\");\n            }\n            // Parse eagerly so configuration failures surface before the source thread starts.\n            Vgtid.of(specificVgtid);\n        }\n\n        return new VitessSourceConfig(options, catalogTables, startupMode, specificVgtid);\n    }\n\n    /** Returns the user-facing connector name used by plugin registration. */\n    public String getPluginName() {\n        return \"Vitess-CDC\";\n    }\n\n    /** Returns the resolved output tables. */\n    public List<CatalogTable> getCatalogTables() {\n        return catalogTables;\n    }","sourceCodeStart":98,"sourceCodeEnd":134,"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/config/VitessSourceConfig.java#L98-L134","documentation":"Thrown when startup.mode is set to 'specific' but startup.specific-offset.vgtid is missing. The connector needs an explicit VGtid (Vitess Global Transaction Identifier) to know where to start streaming, and it parses it eagerly at config time so errors surface before the source thread starts.","triggerScenarios":"Configuring VitessSourceOptions.STARTUP_MODE = StartupMode.SPECIFIC while omitting STARTUP_SPECIFIC_OFFSET_VGTID (or passing a null/empty value) when calling VitessSourceConfig.of.","commonSituations":"Switching startup.mode to specific without copying the vgtid from a prior checkpoint/savepoint; incomplete HOCON/properties config files; a placeholder vgtid left empty after templating.","solutions":["Set startup.specific-offset.vgtid to a valid VGtid string obtained from Vitess (e.g. from VTTablet / vgtid debug output)","Use a different startup.mode (initial, earliest, latest, timestamp) if a specific vgtid is not needed"],"exampleFix":"// before\nstartup { mode = specific }\n// after\nstartup {\n  mode = specific\n  specific-offset { vgtid = \"[\"commerce-0\"]:{\"shard_gtid\":\"...\"}\" }\n}","handlingStrategy":"validation","validationCode":"if (\"specific\".equals(startupMode) && (vgtid == null || vgtid.isEmpty())) {\n    throw new IllegalArgumentException(\"startup.specific-offset.vgtid required for mode=specific\");\n}","typeGuard":null,"tryCatchPattern":"try { VitessSourceConfig.of(tables, options); } catch (IllegalArgumentException e) { /* supply vgtid or switch startup.mode */ }","preventionTips":["Keep vgtid captured from a successful run before switching to mode=specific","Use default startup modes unless resuming from a known VGtid","Validate startup block in your config pipeline"],"tags":["cdc","vitess","startup-offset"],"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-14T16:17:12.679Z"}