apache/seatunnel · error · IllegalArgumentException

Vitess CDC does not support schema-qualified table paths. Ta

Error message

Vitess CDC does not support schema-qualified table paths. Table '%s' contains an unexpected schema component.

What it means

Thrown during Vitess CDC source validation when a table path includes a schema component. Vitess (MySQL-compatible) only has a two-part naming model (keyspace.table), so a three-part or schema-qualified path is invalid for this connector.

Source

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

        }

        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(
                        "startup.specific-offset.vgtid is required when startup.mode=specific.");
            }
            // Parse eagerly so configuration failures surface before the source thread starts.
            Vgtid.of(specificVgtid);
        }

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Remove the schema component and use only keyspace.table
  2. Rebuild the TablePath without a schema name
  3. If a schema-like layer exists, fold it into the table name or use a different connector

Example fix

// before
tablePath = "commerce.public.orders"
// after
tablePath = "commerce.orders"
Defensive patterns

Strategy: validation

Validate before calling

if (tablePath.getSchemaName() != null) {
    throw new IllegalArgumentException("Vitess table paths must be keyspace.table: " + tablePath);
}

Try / catch

try { VitessSourceConfig.of(tables, options); } catch (IllegalArgumentException e) { /* strip schema segment and retry */ }

Prevention

When it happens

Trigger: Calling VitessSourceConfig.of with a CatalogTable whose TablePath.getSchemaName() is non-null, i.e. the table path was parsed with an extra schema segment (e.g. database.schema.table).

Common situations: Reusing table path formats from PostgreSQL-style CDC sources (db.schema.table); programmatically building TablePath with setSchemaName; pasting fully-qualified JDBC identifiers into the Vitess source config.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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