apache/seatunnel · error · IllegalArgumentException

Please configure unique `table_path`, not allow null/duplica

Error message

Please configure unique `table_path`, not allow null/duplicate table path:

What it means

JdbcSourceTableConfig.of validates that every table in the source's table_list has a distinct, non-null table_path. It builds a Set of table paths and throws IllegalArgumentException when duplicates/nulls make the set smaller than the list. Duplicate table paths would otherwise cause the same table to be read/split twice.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/config/JdbcSourceTableConfig.java:115

                    if (tableConfig.getPartitionNumber() == null) {
                        tableConfig.setPartitionNumber(DEFAULT_PARTITION_NUMBER);
                    }
                    tableConfig.setUseSelectCount(
                            connectorConfig.get(JdbcSourceOptions.USE_SELECT_COUNT));
                    tableConfig.setSkipAnalyze(connectorConfig.get(JdbcSourceOptions.SKIP_ANALYZE));
                    if (tableConfig.getUseRegex() == null) {
                        tableConfig.setUseRegex(connectorConfig.get(JdbcSourceOptions.USE_REGEX));
                    }
                });

        if (tableList.size() > 1) {
            List<String> tableIds =
                    tableList.stream()
                            .map(JdbcSourceTableConfig::getTablePath)
                            .collect(Collectors.toList());
            Set<String> tableIdSet = new HashSet<>(tableIds);
            if (tableIdSet.size() < tableList.size() - 1) {
                throw new IllegalArgumentException(
                        "Please configure unique `table_path`, not allow null/duplicate table path: "
                                + tableIds);
            }
        }
        return tableList;
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

Give each entry in table_list a unique table_path, e.g. "schema_a.table1" vs "schema_a.table2"
Confirm every entry defines table_path (check for typos like table-path or tablename)
Read the message's trailing tableIds list to find which entries are duplicated or null
If you truly need the same table twice, merge the configs or use different queries instead

Example fix

// before
table_list = [
  {table_path = "public.users"},
  {table_path = "public.users"}   // duplicate
]
// after
table_list = [
  {table_path = "public.users"},
  {table_path = "public.orders"}
]

Defensive patterns

Strategy: validation

Validate before calling

Set<String> paths = new HashSet<>();
for (Map<String,Object> t : tableList) {
    String p = (String) t.get("table_path");
    if (p == null || !paths.add(p)) {
        throw new IllegalArgumentException("null/duplicate table_path: " + p);
    }
}

Type guard

static boolean hasUniqueTablePaths(List<JdbcSourceTableConfig> list) {
    Set<String> s = new HashSet<>();
    for (JdbcSourceTableConfig c : list) {
        if (c.getTablePath() == null || !s.add(c.getTablePath())) return false;
    }
    return true;
}

Try / catch

try {
    tables = JdbcSourceTableConfig.of(config);
} catch (IllegalArgumentException e) {
    LOG.error("table_list misconfigured: {}", e.getMessage());
    throw new ConfigException(e);
}

Prevention

Keep each table entry's table_path distinct (schema.table)
Search config for repeated table_path values before submitting
Never rely on default null table_path; set it explicitly
Generate table_list programmatically from a deduplicated source

When it happens

Trigger: Calling JdbcSourceTableConfig.of with a table_list where two entries share the same table_path, or where an entry's table_path is null (e.g. table_path key missing or misspelled in config).

Common situations: Copy-pasting a table entry in the HOCON/YAML config and forgetting to change table_path, missing the table_path key so the field defaults to null, case differences ignored when intending different tables.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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