apache/seatunnel · error · SeaTunnelException

DB2 CDC table-names must use database.schema.table format, b

Error message

DB2 CDC table-names must use database.schema.table format, but found: ${configuredTable}

What it means

TableDiscoveryUtils.toConfiguredDb2TableId parses each configured table-name expecting database.schema.table. If a name lacks both dots, or the string ends right after the second dot (empty table part), it throws SeaTunnelException rejecting the malformed name before capture validation can proceed.

Source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-db2/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/db2/utils/TableDiscoveryUtils.java:95

            }
        }
        if (!missingTables.isEmpty()) {
            throw new SeaTunnelException(
                    "The following configured DB2 tables are not enabled for capture: "
                            + String.join(", ", missingTables));
        }
    }

    /**
     * Db2 Debezium metadata always uses an empty catalog because one connector instance captures a
     * single configured database. Explicit SeaTunnel table names still carry the database segment,
     * so startup validation needs to drop that catalog part before comparing with capture tables.
     */
    static TableId toConfiguredDb2TableId(String configuredTable) {
        int firstDot = configuredTable.indexOf('.');
        int secondDot = configuredTable.indexOf('.', firstDot + 1);
        if (firstDot < 0 || secondDot < 0 || secondDot == configuredTable.length() - 1) {
            throw new SeaTunnelException(
                    "DB2 CDC table-names must use database.schema.table format, but found: "
                            + configuredTable);
        }
        return new TableId(
                "",
                configuredTable.substring(firstDot + 1, secondDot),
                configuredTable.substring(secondDot + 1));
    }

    /**
     * Debezium change-table discovery emits empty-catalog {@link TableId}s for Db2, so startup
     * validation normalizes both sides to the same shape before comparing them.
     */
    static TableId normalizeCapturedTableId(TableId tableId) {
        return new TableId("", tableId.schema(), tableId.table());
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

Change the configured value to full three-part form database.schema.table
Ensure no trailing dot and all three segments are non-empty
Uppercase segments to match DB2 metadata if needed

Example fix

// before
table-names = ["MYSCHEMA.MYTABLE"]
// after
table-names = ["MYDB.MYSCHEMA.MYTABLE"]

Defensive patterns

Strategy: validation

Validate before calling

// Validate table-names format before submitting the job
for (String t : tableNames) { String[] p = t.split("\\."); if (p.length != 3 || p[0].isEmpty() || p[1].isEmpty() || p[2].isEmpty()) throw new IllegalArgumentException("table-names must be database.schema.table: " + t); }

Try / catch

try { sourceFactory.createSource(...); } catch (SeaTunnelException e) { if (e.getMessage().contains("must use database.schema.table format")) { /* fix the offending entry named in the message */ } throw e; }

Prevention

Always use three-part database.schema.table names in table-names
No trailing dots or empty segments
Diff config against a working example for the DB2 CDC connector

When it happens

Trigger: Configuring table-names with only schema.table (two parts) or a bare table name, or a trailing dot like 'db.schema.' — any value that doesn't split into three non-empty parts.

Common situations: Users copy Kafka-style schema.table patterns from other CDC connectors; missing schema or database qualifier; typo/trailing dot in YAML list.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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