apache/seatunnel · error · IllegalArgumentException

Vitess CDC requires resolved catalog tables for deterministi

Error message

Vitess CDC requires resolved catalog tables for deterministic table identity.

What it means

VitessSourceConfig.of requires a non-empty, pre-resolved list of CatalogTable objects because Vitess does not expose database/schema names the way MySQL-based connectors do; table identity must be deterministic before the source starts. An empty or null list means the source cannot establish which tables to read, so it 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:84

            ReadonlyConfig options,
            List<CatalogTable> catalogTables,
            StartupMode startupMode,
            String specificStartupVgtid) {
        this.options = options;
        this.catalogTables = Collections.unmodifiableList(new ArrayList<>(catalogTables));
        this.startupMode = startupMode;
        this.specificStartupVgtid = specificStartupVgtid;
    }

    /**
     * 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));
            }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Fix the table include patterns/paths so at least one catalog table resolves
2. Ensure the catalog resolution step runs and returns CatalogTable objects before building VitessSourceConfig
3. Verify keyspace and table names against the live Vitess cluster (show tables in the keyspace)
4. Pass the explicit table list in config if automatic discovery yields nothing

Example fix

// before
List<CatalogTable> tables = catalog.resolve(pattern); // returns []
VitessSourceConfig.of(options, tables); // throws
// after: validate before building
if (tables == null || tables.isEmpty()) {
    throw new IllegalArgumentException("No tables matched; check keyspace/table patterns");
}
VitessSourceConfig.of(options, tables);

List<CatalogTable> tables = resolveCatalogTables(options);
if (tables == null || tables.isEmpty()) {
    throw new IllegalArgumentException("No catalog tables resolved; fix keyspace/table patterns before building VitessSourceConfig");
}
VitessSourceConfig.of(options, tables);

static boolean hasResolvedTables(List<CatalogTable> tables) {
    return tables != null && !tables.isEmpty();
}

try {
    cfg = VitessSourceConfig.of(options, catalogTables);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("requires resolved catalog tables")) {
        LOG.error("Table patterns matched nothing; check keyspace and include lists");
    }
    throw e;
}

When it happens

Trigger: Calling VitessSourceConfig.of(options, catalogTables) with null or an empty catalogTables list — typically when upstream catalog/table resolution returned nothing, e.g. table-path patterns matched no tables or catalog discovery was skipped.

Common situations: Configuring table patterns that match zero tables in the keyspace; running through a code path that passes tables lazily instead of resolved CatalogTables; typos in table include lists so no catalog tables are produced.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Vitess CDC requires database-qualified table paths, but tabl
• tables_configs can not be empty.
• Incremental snapshot for tables requires primary key, but ta
• The following configured DB2 tables are not enabled for capt
• DB2 CDC table-names must use database.schema.table format, b

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