apache/seatunnel · error · IllegalArgumentException

Invalid DuckDB JDBC url:

Error message

Invalid DuckDB JDBC url: 

What it means

DuckDBURLParser.parse validates a JDBC URL against the regex ^jdbc:duckdb:<path>(?<suffix>?query)?$ and throws IllegalArgumentException when the URL does not match. This means the URL is not a syntactically valid DuckDB JDBC URL, so the catalog cannot extract the database path.

Source

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

import java.util.regex.Matcher;
import java.util.regex.Pattern;

/**
 * Parser for DuckDB JDBC URLs.
 *
 * <p>DuckDB is an embedded database, so URLs look like {@code jdbc:duckdb:}, {@code
 * jdbc:duckdb:/path/to/file.duckdb} or {@code jdbc:duckdb:memory:?option=value}. This parser
 * extracts the embedded database path (if any) and builds {@link JdbcUrlUtil.UrlInfo} accordingly.
 */
public class DuckDBURLParser {

    private static final Pattern DUCKDB_URL_PATTERN =
            Pattern.compile("^jdbc:duckdb:(?<path>[^?]*?)(?<suffix>\\?.*)?$");

    public static JdbcUrlUtil.UrlInfo parse(String url) {
        Matcher matcher = DUCKDB_URL_PATTERN.matcher(url);
        if (!matcher.matches()) {
            throw new IllegalArgumentException("Invalid DuckDB JDBC url: " + url);
        }
        String path = Optional.ofNullable(matcher.group("path")).orElse("");
        String suffix = Optional.ofNullable(matcher.group("suffix")).orElse("");
        return new JdbcUrlUtil.UrlInfo(url, "jdbc:duckdb:", "localhost", 0, path, suffix);
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Rewrite the URL to the form jdbc:duckdb:<path>[?params], e.g. jdbc:duckdb:/data/mydb.duckdb
2. Remove any protocol/host/port portion — DuckDB is embedded, no host:port in the URL
3. URL-encode or move invalid characters; the path segment cannot contain characters that break the regex
4. Trim whitespace and check for typos in the scheme (all lowercase jdbc:duckdb:)

Example fix

// before
String url = "duckdb:///data/mydb.duckdb"; // throws
// after
String url = "jdbc:duckdb:/data/mydb.duckdb";

public static boolean isValidDuckDbUrl(String url) {
    return url != null && url.matches("^jdbc:duckdb:[^?]*(\\?.*)?$");
}

try {
    JdbcUrlUtil.UrlInfo info = DuckDBURLParser.parse(url);
} catch (IllegalArgumentException e) {
    LOG.error("Bad DuckDB URL '{}': must be jdbc:duckdb:<path>", url);
}

When it happens

Trigger: Calling parse with a URL that is null, empty, lacks the jdbc:duckdb: prefix (e.g. jdbc:mysql:..., duckdb://..., or a plain file path), or otherwise does not match the pattern.

Common situations: Copy-pasting a URL from another database's config; forgetting the jdbc:duckdb: prefix; using a URL that points at a server (jdbc:duckdb://host:port) which the pattern does not accept; extra whitespace.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Table URL cannot be null or empty
• Invalid table URL format: '%s'. Expected format: http://host
• Invalid Firebase REST URI constructed. Check parameter forma
• Failed connecting to the configured JDBC URL via JDBC.
• Invalid Oracle JDBC URL format: [%s], expected pattern: jdbc

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