apache/seatunnel · error · IllegalArgumentException

The jdbc url format is incorrect: ${url}

Error message

The jdbc url format is incorrect: ${url}

What it means

JdbcUrlUtil.getUrlInfo parses a JDBC URL into host, port, database and suffix parts. It throws this IllegalArgumentException when the URL does not match the supported JDBC URL regex (scheme://host:port[/database][?suffix]). The library throws it to fail fast on URLs it cannot decompose rather than returning partial data.

Source

Thrown at seatunnel-common/src/main/java/org/apache/seatunnel/common/utils/JdbcUrlUtil.java:49

            Pattern.compile(
                    "^(?<url>jdbc:.+?//(?<host>.+?):(?<port>\\d+?))(/(?<database>.*?))*(?<suffix>\\?.*)*$");

    private JdbcUrlUtil() {}

    public static JdbcUrlUtil.UrlInfo getUrlInfo(String url) {
        Matcher matcher = URL_PATTERN.matcher(url);
        if (matcher.find()) {
            String urlWithoutDatabase = matcher.group("url");
            String database = matcher.group("database");
            return new JdbcUrlUtil.UrlInfo(
                    url,
                    urlWithoutDatabase,
                    matcher.group("host"),
                    Integer.valueOf(matcher.group("port")),
                    database,
                    matcher.group("suffix"));
        }
        throw new IllegalArgumentException("The jdbc url format is incorrect: " + url);
    }

    @Data
    public static class UrlInfo implements Serializable {
        private static final long serialVersionUID = 1L;
        private final String origin;
        private final String urlWithoutDatabase;
        private final String host;
        private final Integer port;
        private final String suffix;
        private final String defaultDatabase;

        public UrlInfo(
                String origin,
                String urlWithoutDatabase,
                String host,
                Integer port,
                String defaultDatabase,

View on GitHub (pinned to cf67b549a7)

Solutions

1. Print and inspect the exact url string; verify it matches pattern jdbc:<db>://<host>:<port>[/<database>][?<params>]
2. Fix scheme typos and remove whitespace/quotes from the connection string
3. For vendor-specific URL styles not supported (SID vs service name, unix sockets), convert to the standard host:port form
4. If the URL comes from config, validate it with a regex before passing to getUrlInfo

Example fix

// before
String url = "jdbc:mysql//localhost:3306/mydb"; // missing ':' after mysql
UrlInfo info = JdbcUrlUtil.getUrlInfo(url);
// after
String url = "jdbc:mysql://localhost:3306/mydb";
UrlInfo info = JdbcUrlUtil.getUrlInfo(url);

boolean looksLikeJdbcUrl(String url) {
    return url != null && url.matches("jdbc:[a-zA-Z0-9]+://[^:/\\s]+:\\d+(/[\\w.-]+)?(\\?.*)?");
}
if (!looksLikeJdbcUrl(url)) throw new IllegalArgumentException("unsupported jdbc url: " + url);

When it happens

Trigger: Calling JdbcUrlUtil.getUrlInfo(url) with a URL that lacks the expected scheme, omits host or port, contains unexpected characters, or otherwise fails the built-in matcher.

Common situations: Typo in the jdbc scheme (e.g. 'jdbc:mysql//host' missing colon), using a connection string style the parser doesn't support (e.g. jdbc:oracle:thin:@host:port:sid SID style), hostnames with underscores, copied URLs with stray spaces or quotes, database name embedded differently per vendor dialect.

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

• Retry times must be greater than 0
• Invalid AmazonDocumentDB connection URI in option 'uri'
• Failed to get connection, interrupted while doing another at
• Get connection failed after retry times
• Failed to discover captured tables for enumerator

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