apache/seatunnel · error · IllegalArgumentException

Hive `table_name` must use `databasePattern.tablePattern` wh

Error message

Hive `table_name` must use `databasePattern.tablePattern` when `use_regex` is enabled. Invalid `table_name`: 

What it means

Hive table discovery expects `table_name` in the exact form `databasePattern.tablePattern` — exactly one unescaped dot separating a database regex from a table regex. If findTableSeparator finds no unescaped dot at all, parse has no way to split the pattern and throws this error, echoing the processed pattern back to the user.

Source

Thrown at seatunnel-connectors-v2/connector-hive/src/main/java/org/apache/seatunnel/connectors/seatunnel/hive/source/config/HiveTableNamePattern.java:43

    private final String databasePattern;
    private final String tablePattern;

    private HiveTableNamePattern(String databasePattern, String tablePattern) {
        this.databasePattern = databasePattern;
        this.tablePattern = tablePattern;
    }

    static HiveTableNamePattern parse(String rawPattern) {
        if (rawPattern == null || rawPattern.trim().isEmpty()) {
            throw new IllegalArgumentException(
                    "`table_name` must not be blank when `use_regex` is enabled");
        }

        String processed = rawPattern.trim().replace("\\.", DOT_PLACEHOLDER);
        Optional<Integer> separatorIndex = findTableSeparator(processed);
        if (!separatorIndex.isPresent()) {
            throw new IllegalArgumentException(
                    "Hive `table_name` must use `databasePattern.tablePattern` when `use_regex` is enabled. "
                            + "Invalid `table_name`: "
                            + processed.replace(DOT_PLACEHOLDER, "."));
        }

        int index = separatorIndex.get();
        String databasePattern = processed.substring(0, index).trim();
        String tablePattern = processed.substring(index + 1).trim();

        if (databasePattern.isEmpty() || tablePattern.isEmpty()) {
            throw new IllegalArgumentException(
                    "Hive `table_name` must use `databasePattern.tablePattern` when `use_regex` is enabled. "
                            + "Invalid `table_name`: "
                            + processed.replace(DOT_PLACEHOLDER, "."));
        }

        databasePattern = databasePattern.replace(DOT_PLACEHOLDER, ".");
        tablePattern = tablePattern.replace(DOT_PLACEHOLDER, ".");

View on GitHub (pinned to cf67b549a7)

Solutions

1. Write `table_name` as `dbPattern.tablePattern` with exactly one unescaped dot, e.g. "mydb.\\.*"
2. If a literal dot is needed inside a fragment, keep it escaped as `\\.` (written `\\\\.` in HOCON) and leave the separator dot unescaped
3. Check the documented examples: `db0.\\.*`, `db1.user_table_[0-9]+`, `db[1-2].[app|web]order_\\.*`

Example fix

// before
table_name = "user_table_[0-9]+" // no db separator

// after
table_name = "db1.user_table_[0-9]+"

if (!raw.trim().matches("[^.]+\\..+")) {
    throw new IllegalArgumentException("table_name must be dbPattern.tablePattern with one unescaped dot");
}

When it happens

Trigger: Calling HiveTableNamePattern.parse with a string containing no unescaped '.' (e.g. "mytable" or "db\\.table" where the only dot is escaped as a literal), while use_regex is enabled.

Common situations: User provides only a table name without a database prefix; user escapes the separating dot by mistake (`db\\.t`), leaving zero separators; configs copied from non-regex Hive setups that use plain `db.table` plus escaping confusion.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• When `use_regex` is enabled, `table_name` must be configured
• Invalid regex pattern in `table_name`: , resolved pattern:
• `table_name` must not be blank when `use_regex` is enabled
• Hive does not support schema in `table_name` when `use_regex
• UNSUPPORTED_DATA_TYPE

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