apache/seatunnel · error · IllegalArgumentException

startup.specific-offset.vgtid is required when startup.mode=

Error message

startup.specific-offset.vgtid is required when startup.mode=specific.

What it means

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.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-vitess/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/vitess/config/VitessSourceConfig.java:116

                throw new IllegalArgumentException(
                        String.format(
                                "Vitess CDC captures one keyspace per source. Table '%s' does not belong to keyspace '%s'.",
                                catalogTable.getTablePath(), keyspace));
            }
            if (catalogTable.getTablePath().getSchemaName() != null) {
                throw new IllegalArgumentException(
                        String.format(
                                "Vitess CDC does not support schema-qualified table paths. Table '%s' contains an unexpected schema component.",
                                catalogTable.getTablePath()));
            }
        }

        StartupMode startupMode = options.get(VitessSourceOptions.STARTUP_MODE);
        String specificVgtid =
                options.getOptional(VitessSourceOptions.STARTUP_SPECIFIC_OFFSET_VGTID).orElse(null);
        if (startupMode == StartupMode.SPECIFIC) {
            if (specificVgtid == null) {
                throw new IllegalArgumentException(
                        "startup.specific-offset.vgtid is required when startup.mode=specific.");
            }
            // Parse eagerly so configuration failures surface before the source thread starts.
            Vgtid.of(specificVgtid);
        }

        return new VitessSourceConfig(options, catalogTables, startupMode, specificVgtid);
    }

    /** Returns the user-facing connector name used by plugin registration. */
    public String getPluginName() {
        return "Vitess-CDC";
    }

    /** Returns the resolved output tables. */
    public List<CatalogTable> getCatalogTables() {
        return catalogTables;
    }

View on GitHub (pinned to cf67b549a7)

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

Example fix

// before
startup { mode = specific }
// after
startup {
  mode = specific
  specific-offset { vgtid = "["commerce-0"]:{"shard_gtid":"..."}" }
}

Defensive patterns

Strategy: validation

Validate before calling

if ("specific".equals(startupMode) && (vgtid == null || vgtid.isEmpty())) {
    throw new IllegalArgumentException("startup.specific-offset.vgtid required for mode=specific");
}

Try / catch

try { VitessSourceConfig.of(tables, options); } catch (IllegalArgumentException e) { /* supply vgtid or switch startup.mode */ }

Prevention

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

When it happens

Trigger: Configuring VitessSourceOptions.STARTUP_MODE = StartupMode.SPECIFIC while omitting STARTUP_SPECIFIC_OFFSET_VGTID (or passing a null/empty value) when calling VitessSourceConfig.of.

Common situations: 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.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/0ddd473f5b927b93. Report an issue: GitHub.