apache/seatunnel · error · IllegalArgumentException

Either table path or query must be specified in source…

Error message

Either table path or query must be specified in source configuration.

What it means

JdbcCatalogUtils builds a CatalogTable for each configured source table. Each table entry must provide either a table_path or a query; if both are missing, getCatalogTable throws IllegalArgumentException. This is a configuration-validation error thrown before any database interaction.

Solutions

Add table_path (e.g. "database_name.table_name") to each table_list entry, or
Provide a query (e.g. "SELECT * FROM db.table WHERE dt='2024-01-01'") instead
Fix option-name typos and verify substituted variables are non-empty in the rendered config

Example fix

// before
JdbcSourceTableConfig t = new JdbcSourceTableConfig();
t.setTablePath("");
t.setQuery(null);
// after
JdbcSourceTableConfig t = new JdbcSourceTableConfig();
t.setTablePath("mydb.mytable"); // or t.setQuery("SELECT * FROM mydb.mytable")

Defensive patterns

Strategy: validation

Validate before calling

import com.google.common.base.Strings;
if (Strings.isNullOrEmpty(tableConfig.getTablePath()) && Strings.isNullOrEmpty(tableConfig.getQuery())) {
  throw new IllegalArgumentException("table_list entry needs table_path or query");
}

Try / catch

try {
  CatalogTable ct = JdbcCatalogUtils.getCatalogTable(tableConfig, jdbcCatalog, dialect);
} catch (IllegalArgumentException e) {
  log.error("Fix source config: {}", e.getMessage());
}

Prevention

Ensure every table_list entry sets table_path or query
Watch for option-name typos (tablepath vs table_path)
Verify template variables render to non-empty values

When it happens

Trigger: A JdbcSourceTableConfig in the source's table_list (or single-table config) has an empty/absent table_path and an empty/absent query when getCatalogTable (catalog-driven overload) resolves the table.

Common situations: table_list entry with only a database or catalog but no table name; typo such as tablepath or tabel_path; empty string values after variable substitution; user intended to set query but left it blank.

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/418b47e37c77357b. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/utils/JdbcCatalogUtils.java:240

            throw (SQLException) error;
        }
        if (error instanceof ClassNotFoundException) {
            throw (ClassNotFoundException) error;
        }
        if (error instanceof RuntimeException) {
            return (RuntimeException) error;
        }
        return new RuntimeException(error);
    }

    private static CatalogTable getCatalogTable(
            JdbcSourceTableConfig tableConfig,
            AbstractJdbcCatalog jdbcCatalog,
            JdbcDialect jdbcDialect)
            throws SQLException {
        if (Strings.isNullOrEmpty(tableConfig.getTablePath())
                && Strings.isNullOrEmpty(tableConfig.getQuery())) {
            throw new IllegalArgumentException(
                    "Either table path or query must be specified in source configuration.");
        }

        if (StringUtils.isNotEmpty(tableConfig.getTablePath())
                && StringUtils.isNotEmpty(tableConfig.getQuery())) {
            TablePath tablePath = jdbcDialect.parse(tableConfig.getTablePath());
            CatalogTable tableOfPath = null;
            try {
                tableOfPath = jdbcCatalog.getTable(tablePath);
            } catch (Exception e) {
                // ignore
                log.debug("User-defined table path: {}", tablePath);
            }
            CatalogTable tableOfQuery = jdbcCatalog.getTable(tableConfig.getQuery());
            if (tableOfPath == null) {
                String catalogName =
                        tableOfQuery.getTableId() == null
                                ? DEFAULT_CATALOG_NAME

View on GitHub (pinned to cf67b549a7)