apache/seatunnel · error · IllegalArgumentException

When `use_regex` is enabled, `table_name` must be configured

Error message

When `use_regex` is enabled, `table_name` must be configured

What it means

When `use_regex = true`, Hive table discovery uses the `table_name` option as a regex pattern (`databasePattern.tablePattern`) to filter metastore tables. This error is thrown from discoverTablePaths when the option is absent or blank, because there is no pattern to compile or match against. It is an explicit configuration sanity check before touching the Hive metastore.

Source

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

@UtilityClass
public class HiveSourceTableDiscovery {

    public static boolean isEnabled(ReadonlyConfig config) {
        return config != null && config.get(HiveSourceOptions.USE_REGEX);
    }

    public static List<TablePath> discoverTablePaths(ReadonlyConfig config, Catalog catalog) {
        if (config == null || catalog == null) {
            return Collections.emptyList();
        }

        if (!config.get(HiveSourceOptions.USE_REGEX)) {
            return Collections.emptyList();
        }

        String patternStr = config.getOptional(HiveSourceOptions.TABLE_NAME).orElse(null);
        if (patternStr == null || patternStr.trim().isEmpty()) {
            throw new IllegalArgumentException(
                    "When `use_regex` is enabled, `table_name` must be configured");
        }

        HiveTableNamePattern tableNamePattern = HiveTableNamePattern.parse(patternStr);
        Pattern databasePattern = compilePattern(tableNamePattern.getDatabasePattern(), patternStr);
        Pattern tablePattern = compilePattern(tableNamePattern.getTablePattern(), patternStr);

        List<TablePath> tablePaths = new ArrayList<>();
        String databasePatternStr = tableNamePattern.getDatabasePattern();
        if (isExactDatabaseName(databasePatternStr)) {
            String databaseName = databasePatternStr;
            for (String tableName : catalog.listTables(databaseName)) {
                if (tablePattern.matcher(tableName).matches()) {
                    tablePaths.add(TablePath.of(databaseName, tableName));
                }
            }
        } else {
            for (String databaseName : catalog.listDatabases()) {

View on GitHub (pinned to cf67b549a7)

Solutions

Set `table_name` in the Hive source config, e.g. table_name = "db0.\\.*"
Disable `use_regex` (set it to false or remove it) if you intend to read an explicit table list instead
Validate the config before submitting: ensure table_name is present and non-blank whenever use_regex is true

Example fix

// before
use_regex = true
// (no table_name)

// after
use_regex = true
table_name = "db0.\\.*"

Defensive patterns

Strategy: validation

Validate before calling

if (config.get(HiveSourceOptions.USE_REGEX)
        && !config.getOptional(HiveSourceOptions.TABLE_NAME).map(s -> !s.trim().isEmpty()).orElse(false)) {
    throw new IllegalArgumentException("use_regex=true requires a non-blank table_name");
}

Prevention

Always pair use_regex=true with a table_name pattern
Validate HOCON templates after variable substitution
Prefer explicit table lists when only one table is read

When it happens

Trigger: Calling HiveSourceTableDiscovery.discoverTablePaths (directly or via MultipleTableHiveSourceConfig.expandTableConfigIfNeeded) with a config where HiveSourceOptions.USE_REGEX is true but HiveSourceOptions.TABLE_NAME is missing, null, or whitespace-only.

Common situations: Users enable `use_regex = true` to bulk-read tables but forget the `table_name` option; a templated/generated HOCON config leaves `table_name` empty; a refactor renames the option so the value falls back to default null.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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