apache/seatunnel · critical · CatalogException

Failed connecting to the configured JDBC URL via JDBC.

Error message

Failed connecting to the configured JDBC URL via JDBC.

What it means

DuckDBCatalog wraps any SQLException thrown by DriverManager.getConnection when opening a JDBC connection to the configured DuckDB URL. The original SQLException is chained as the cause, so the real reason (bad path, driver missing, lock contention) is in e.getCause(). It signals the catalog could not establish the connection it needs for metadata operations.

Source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/catalog/duckdb/DuckDBCatalog.java:127

                        try {
                            Connection connection = driver.connect(url, info);
                            connectionMap.put(url, connection);
                            return connection;
                        } catch (Exception e) {
                            log.info("try connector failed", e);
                        }
                    }
                }
            } catch (Exception e) {
                log.info("find driver error, back to DriverManager.getConnection", e);
            }
        }
        try {
            Connection connection = DriverManager.getConnection(url, info);
            connectionMap.put(url, connection);
            return connection;
        } catch (SQLException e) {
            throw new CatalogException("Failed connecting to the configured JDBC URL via JDBC.", e);
        }
    }

    @Override
    public List<CatalogTable> getTables(ReadonlyConfig config) throws CatalogException {
        // Get the list of specified tables
        List<String> tableNames = config.get(ConnectorCommonOptions.TABLE_NAMES);
        if (tableNames != null && !tableNames.isEmpty()) {
            Iterator<TablePath> tablePaths =
                    tableNames.stream().map(TablePath::of).filter(this::tableExists).iterator();
            return buildCatalogTablesWithErrorCheck(tablePaths, config);
        }
        // Get the list of table pattern
        String tablePatternStr = config.get(ConnectorCommonOptions.TABLE_PATTERN);
        if (StringUtils.isBlank(tablePatternStr)) {
            return Collections.emptyList();
        }
        Pattern tablePattern = Pattern.compile(tablePatternStr);

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Check the chained cause (e.getCause()) for the underlying SQLException message
  2. Verify the DuckDB JDBC driver jar is present in the connector classpath (or run install-plugin.sh)
  3. Ensure no other process holds an exclusive lock on the DuckDB database file; close other clients
  4. Validate the URL matches jdbc:duckdb:<path> format (see DuckDBURLParser)
  5. Verify the database file directory exists and is writable

Example fix

// before
Connection conn = catalog.getConnection(url, info); // throws CatalogException
// after
try {
    Connection conn = catalog.getConnection(url, info);
} catch (CatalogException e) {
    LOG.error("DuckDB connect failed: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage());
    throw e;
}
Defensive patterns

Strategy: try-catch

Validate before calling

String url = config.getUrl();
if (url == null || !url.startsWith("jdbc:duckdb:")) {
    throw new IllegalArgumentException("Not a DuckDB JDBC URL: " + url);
}
DuckDBURLParser.parse(url); // throws early if malformed

Try / catch

try {
    Connection c = catalog.getConnection(url, info);
} catch (CatalogException e) {
    Throwable cause = e.getCause();
    LOG.error("DuckDB connection failed: {}", cause, cause);
    throw new RuntimeException("Check driver classpath and DuckDB file lock", e);
}

Prevention

When it happens

Trigger: Calling getConnection (directly or via any catalog metadata operation like listTables/getTable) when DriverManager.getConnection(url, info) throws an SQLException: malformed URL, DuckDB driver not on classpath, database file locked by another process, or invalid connection properties.

Common situations: DuckDB driver (duckdb_jdbc) missing from the plugin/lib directory; the DuckDB file is already opened exclusively by another process (DuckDB allows only one writer); wrong jdbc:duckdb: URL syntax; file path not writable.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

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