apache/seatunnel · error · IllegalArgumentException

Vitess CDC captures one keyspace per source. Table '%s' does

Error message

Vitess CDC captures one keyspace per source. Table '%s' does not belong to keyspace '%s'.

What it means

This IllegalArgumentException is thrown during Vitess CDC source configuration validation when a table path's database (keyspace) portion does not match the keyspace configured for the source. Vitess CDC captures change streams for exactly one keyspace per source instance, so all declared tables must belong to that keyspace.

Source

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

     * table paths must already be deterministic before the source starts.
     */
    public static VitessSourceConfig of(ReadonlyConfig options, List<CatalogTable> catalogTables) {
        if (catalogTables == null || catalogTables.isEmpty()) {
            throw new IllegalArgumentException(
                    "Vitess CDC requires resolved catalog tables for deterministic table identity.");
        }

        String keyspace = options.get(VitessSourceOptions.KEYSPACE);
        for (CatalogTable catalogTable : catalogTables) {
            String databaseName = catalogTable.getTablePath().getDatabaseName();
            if (databaseName == null) {
                throw new IllegalArgumentException(
                        String.format(
                                "Vitess CDC requires database-qualified table paths, but table '%s' does not define a database name.",
                                catalogTable.getTablePath()));
            }
            if (!keyspace.equals(databaseName)) {
                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(

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Align the table's database name with the configured keyspace option, e.g. change table path to keyspace.table
  2. Change the keyspace option to match the tables you actually declared
  3. Split into multiple Vitess CDC sources, one per keyspace

Example fix

// before
tables = ["commerce.orders", "customer.users"] with keyspace = "commerce"
// after
tables = ["commerce.orders", "commerce.users"] with keyspace = "commerce"
Defensive patterns

Strategy: validation

Validate before calling

String keyspace = options.get(VitessSourceOptions.KEYSPACE);
for (String table : tables) {
    if (!table.startsWith(keyspace + ".")) {
        throw new IllegalArgumentException("table " + table + " not in keyspace " + keyspace);
    }
}

Try / catch

try { VitessSourceConfig.of(catalogTables, options); } catch (IllegalArgumentException e) { /* fix keyspace/table mismatch before resubmitting */ }

Prevention

When it happens

Trigger: Calling VitessSourceConfig.of (directly or via the Vitess source factory) with a tables list where a CatalogTable's table path resolves to a databaseName different from the configured keyspace option.

Common situations: Copy-pasting table configs from a multi-keyspace job into a single-keyspace source; typos in the keyspace option; renaming a keyspace in Vitess but not updating the table paths; mixing tables from shard-merged keyspaces like 'commerce' and 'customer' in one source.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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