apache/seatunnel · error · IllegalArgumentException

Oracle table name format must be is

Error message

Oracle table name format must be is: ${database}.${schema}.${table} or ${schema}.${table}, table: ${table}

What it means

Thrown by validateConfig when a table in table-list does not have exactly 2 or 3 dot-separated parts. Oracle CDC expects 'DATABASE.SCHEMA.TABLE' or 'SCHEMA.TABLE'; other shapes cannot be resolved to a schema-qualified table and fail validation.

Solutions

Write the table as SCHEMA.TABLE (HR.EMPLOYEES).
Or as DATABASE.SCHEMA.TABLE (ORCLPDB1.HR.EMPLOYEES) matching database-list.
Remove extra dot-separated segments and stray characters from the entry.

Example fix

// before
table-names = ["EMPLOYEES"]
// after
table-names = ["HR.EMPLOYEES"]

Defensive patterns

Strategy: validation

Validate before calling

int parts = table.split("\\.").length;
if (parts != 2 && parts != 3) throw new IllegalArgumentException("use SCHEMA.TABLE or DB.SCHEMA.TABLE: " + table);

Prevention

Validate table-name shape in config CI before job submission.
Avoid embedding quoted identifiers with internal dots in table-list.

When it happens

Trigger: table-list entries like "EMPLOYEES" (1 part), "HR.EMPLOYEES.EXT" (4 parts), or names containing extra dots from quoting mistakes.

Common situations: Users supply a bare table name, reuse a fully qualified name with a partition/subpartition suffix, or accidentally include whitespace/typo dots in the config.

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/969bd9f8a7881bcc. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-connectors-v2/connector-cdc/connector-cdc-oracle/src/main/java/org/apache/seatunnel/connectors/seatunnel/cdc/oracle/config/OracleSourceConfigFactory.java:207

    }

    private void validateConfig() throws IllegalArgumentException {
        if (databaseList.size() != 1) {
            throw new IllegalArgumentException(
                    "Oracle only supports single database, databaseList: " + databaseList);
        }
        for (String database : databaseList) {
            for (int i = 0; i < database.length(); i++) {
                if (Character.isLetter(database.charAt(i))
                        && !Character.isUpperCase(database.charAt(i))) {
                    throw new IllegalArgumentException(
                            "Oracle database name must be in all uppercase, database: " + database);
                }
            }
        }
        for (String table : tableList) {
            if (table.split("\\.").length != 3 && table.split("\\.").length != 2) {
                throw new IllegalArgumentException(
                        "Oracle table name format must be is: ${database}.${schema}.${table} or ${schema}.${table}, table: "
                                + table);
            }
            for (int i = 0; i < table.length(); i++) {
                if (Character.isLetter(table.charAt(i))
                        && !Character.isUpperCase(table.charAt(i))) {
                    throw new IllegalArgumentException(
                            "Oracle table name must be in all uppercase, table: " + table);
                }
            }
        }
    }
}

View on GitHub (pinned to cf67b549a7)