apache/seatunnel · error · IllegalArgumentException
Vitess CDC requires resolved catalog tables for…
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.
Solutions
- Fix the table include patterns/paths so at least one catalog table resolves
- Ensure the catalog resolution step runs and returns CatalogTable objects before building VitessSourceConfig
- Verify keyspace and table names against the live Vitess cluster (show tables in the keyspace)
- 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); Defensive patterns
Strategy: validation
Validate before calling
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); Type guard
static boolean hasResolvedTables(List<CatalogTable> tables) {
return tables != null && !tables.isEmpty();
} Try / catch
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;
} Prevention
- Qualify table patterns with keyspace and verify matches against the live cluster
- Resolve catalog tables synchronously before constructing the source config
- Test table-include patterns in staging with the same keyspace
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
- tables_configs can not be empty.
- Vitess CDC requires database-qualified table paths, but…
- Cannot find table schema for table
- DB2 CDC table-names must use database.schema.table format…
- Incremental snapshot for tables requires primary key, but…
AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10).
Data as JSON: /api/errors/516fc8a928faff62.
Report an issue: GitHub.
Appendix: 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)