apache/seatunnel · error · IllegalArgumentException

Vitess CDC requires database-qualified table paths, but tabl

Error message

Vitess CDC requires database-qualified table paths, but table '%s' does not define a database name.

What it means

VitessSourceConfig.of validates that every resolved CatalogTable has a database-qualified TablePath (a non-null database name), because Vitess table identity is keyspace-scoped and the connector must map each table to its keyspace. A table path without a database name cannot be attributed to a keyspace and fails fast.

Source

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

    }

    /**
     * Builds the validated connector configuration.
     *
     * <p>Vitess does not expose database/schema names the same way as MySQL-based connectors, so
     * 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()));
            }
        }

View on GitHub (pinned to cf67b549a7)

Solutions

Qualify every table with its keyspace/database, e.g. 'commerce.orders' instead of 'orders'
Fix the code that constructs TablePath to include the database name
Ensure upstream catalog resolution preserves the database component of the path
Validate table paths before building the source config

Example fix

// before
TablePath path = TablePath.of(null, "orders");
// after
TablePath path = TablePath.of("commerce", "orders"); // keyspace-qualified

Defensive patterns

Strategy: validation

Validate before calling

for (CatalogTable t : catalogTables) {
    if (t.getTablePath().getDatabaseName() == null) {
        throw new IllegalArgumentException("Table path " + t.getTablePath() + " must be keyspace-qualified, e.g. commerce.orders");
    }
}

Type guard

static boolean isDatabaseQualified(CatalogTable t) {
    return t.getTablePath() != null && t.getTablePath().getDatabaseName() != null;
}

Try / catch

try {
    cfg = VitessSourceConfig.of(options, catalogTables);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("database-qualified table paths")) {
        LOG.error("Qualify every table with its keyspace: keyspace.table");
    }
    throw e;
}

Prevention

Always write table config entries as keyspace.table
Normalize TablePath construction to require the database component
Validate table paths at config-load time, before catalog resolution

When it happens

Trigger: A CatalogTable whose TablePath.getDatabaseName() returns null is passed to VitessSourceConfig.of — e.g. table paths built from bare table names without keyspace/database qualification, or upstream metadata that omits the database part.

Common situations: Configuring tables as 'tablename' instead of 'keyspace.tablename'; catalog tools emitting unqualified paths; programmatic job construction building TablePath with only the table name.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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