apache/beam · error · IllegalArgumentException

Invalid JDBC URL format. Expected 'jdbc:clickhouse:' or…

Error message

Invalid JDBC URL format. Expected 'jdbc:clickhouse:' or 'jdbc:ch:' prefix. Got:

What it means

Thrown by ClickHouseJdbcUrlParser.extractHttpUrl when the part after the leading 'jdbc:' does not start (case-insensitively) with the 'clickhouse:' or 'ch:' vendor prefix. The parser only recognizes these two prefixes so downstream handling operates on a known URL shape.

Solutions

Prefix the URL with 'jdbc:clickhouse:' or the shorter 'jdbc:ch:' before parsing.
Confirm the input is not a URL for another database system.
Check the prefix spelling; comparison is case-insensitive but must match exactly.
Update configuration when migrating from older ClickHouse JDBC driver URL formats.

Example fix

// before
String url = "http://localhost:8123/default"; // missing prefixes
// after
String url = "jdbc:clickhouse:http://localhost:8123/default";

Defensive patterns

Strategy: validation

Validate before calling

boolean hasClickHousePrefix(String url) {
  if (url == null) return false;
  String lower = url.toLowerCase();
  return lower.startsWith("jdbc:clickhouse:") || lower.startsWith("jdbc:ch:");
}

Try / catch

if (!hasClickHousePrefix(jdbcUrl)) {
  throw new ConfigException("URL must start with jdbc:clickhouse: or jdbc:ch:, got: " + jdbcUrl);
}
ParsedJdbcUrl parsed = ClickHouseJdbcUrlParser.parse(jdbcUrl);

Prevention

Centralize JDBC URL construction so the vendor prefix is added in one place.
Use constants like JDBC_PREFIX = "jdbc:clickhouse:" instead of hand-typed strings.
When migrating drivers, grep configs for old prefixes and update them.
Prefix spelling must match exactly ('clickhouse' or 'ch'); case is handled.

When it happens

Trigger: Calling parse() with a URL missing the vendor prefix (e.g. 'http://host:8123'), using another database's URL (jdbc:mysql://...), an alias like 'jdbc:clickhouse+http:', or a typo such as 'jdbc:ClickHose:'.

Common situations: Reusing a JDBC URL written for a different driver in a ClickHouse pipeline; hand-editing the prefix; migrating between older ClickHouse JDBC drivers that used different URL conventions.

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

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/dd87f76fa8dcbce5. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/io/clickhouse/src/main/java/org/apache/beam/sdk/io/clickhouse/ClickHouseJdbcUrlParser.java:140

   * @param jdbcUrl the JDBC URL to process
   * @return normalized HTTP/HTTPS URL
   * @throws IllegalArgumentException if the URL format is invalid
   */
  private static String extractHttpUrl(String jdbcUrl) {
    // Remove jdbc: prefix
    String urlWithoutJdbc = jdbcUrl;
    if (jdbcUrl.toLowerCase().startsWith("jdbc:")) {
      urlWithoutJdbc = jdbcUrl.substring(5);
    }

    // Handle jdbc:clickhouse: or jdbc:ch: prefix
    String actualUrl;
    if (urlWithoutJdbc.toLowerCase().startsWith("clickhouse:")) {
      actualUrl = urlWithoutJdbc.substring(11);
    } else if (urlWithoutJdbc.toLowerCase().startsWith("ch:")) {
      actualUrl = urlWithoutJdbc.substring(3);
    } else {
      throw new IllegalArgumentException(
          "Invalid JDBC URL format. Expected 'jdbc:clickhouse:' or 'jdbc:ch:' prefix. Got: "
              + jdbcUrl);
    }

    boolean useHttps = false;

    // Check if port suggests HTTPS (8443 is default HTTPS port for ClickHouse)
    if (actualUrl.contains(":8443")) {
      useHttps = true;
    }

    // Check if ssl=true in query string
    if (actualUrl.toLowerCase().contains("ssl=true")) {
      useHttps = true;
    }

    // Check for invalid schemes before prepending http://
    if (actualUrl.contains("://")) {

View on GitHub (pinned to 12126d8942)