What causes "Invalid JDBC URL format: " in apache/beam?

Inspect the jdbcUrl in the message and the wrapped URISyntaxException (getCause) for the exact invalid character/position.

apache/beam · error · IllegalArgumentException

Invalid JDBC URL format:

Error message

Invalid JDBC URL format:

What it means

Thrown by ClickHouseJdbcUrlParser.parse when the JDBC URL cannot be syntactically parsed as a URI (the internal URISyntaxException is wrapped in an IllegalArgumentException). The message carries the original jdbcUrl so callers can see exactly which input was rejected.

Solutions

Inspect the jdbcUrl in the message and the wrapped URISyntaxException (getCause) for the exact invalid character/position.
URL-encode path and query components (URLEncoder.encode or the multi-argument URI constructor) before assembling the JDBC URL.
Strip whitespace/quotes from configuration values before passing them to parse().
Pass credentials containing special characters via a Properties object instead of the URL.

Example fix

// before
String url = "jdbc:clickhouse://localhost:8123/default? user=default"; // space in query -> URISyntaxException
// after
String url = "jdbc:clickhouse://localhost:8123/default?user=" + URLEncoder.encode(user, StandardCharsets.UTF_8);

Defensive patterns

Strategy: validation

Validate before calling

boolean isValidJdbcUrl(String url) {
  if (url == null || url.isBlank()) return false;
  int schemeEnd = url.indexOf(':');
  if (schemeEnd < 0 || !url.startsWith("jdbc:")) return false;
  try { new java.net.URI(url.substring(schemeEnd + 1)); return true; }
  catch (java.net.URISyntaxException e) { return false; }
}

Type guard

boolean hasRawSpecialChars(String url) {
  return url != null && url.matches(".*[\\s<>{}|\\\\^`].*");
}

Try / catch

try {
  ParsedJdbcUrl parsed = ClickHouseJdbcUrlParser.parse(jdbcUrl);
} catch (IllegalArgumentException e) {
  LOG.error("Cannot parse JDBC URL {}: {}", jdbcUrl,
      e.getCause() != null ? e.getCause().getMessage() : e.getMessage());
  throw new ConfigException("Malformed ClickHouse JDBC URL", e);
}

Prevention

Build URLs with the multi-argument URI constructor or URLEncoder for path/query parts.
Never embed raw credentials with special characters in the URL; use Properties.
Trim/strip whitespace and quotes from config values before constructing the URL.
Add a startup-time URL validation step with a clear error before the pipeline runs.

When it happens

Trigger: Calling parse() with a jdbc:clickhouse: URL whose authority, port, path or query violates URI syntax: unescaped spaces or special characters, a non-numeric port like host:abc, unbracketed IPv6 literals, or illegal characters in the database path/query.

Common situations: Building the URL by string concatenation from user input or env vars without URL-encoding; copy-pasted URLs with trailing whitespace or quotes; passwords or parameters containing reserved characters (?, #, %, spaces) placed raw in the query string.

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/79844814f345dd1a. Report an issue: GitHub.

Appendix: source

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

    }

    String actualUrl = extractHttpUrl(jdbcUrl);

    try {
      URI uri = new URI(actualUrl);

      validateScheme(uri.getScheme());
      String host = validateAndGetHost(uri.getHost(), jdbcUrl);
      int port = getPortOrDefault(uri.getPort(), uri.getScheme());

      String clickHouseUrl = String.format("%s://%s:%d", uri.getScheme(), host, port);
      String database = extractDatabase(uri.getPath());
      Properties properties = extractProperties(uri.getQuery());

      return new ParsedJdbcUrl(clickHouseUrl, database, properties);

    } catch (URISyntaxException e) {
      throw new IllegalArgumentException("Invalid JDBC URL format: " + jdbcUrl, e);
    } catch (java.io.UnsupportedEncodingException e) {
      throw new IllegalArgumentException("Failed to decode URL parameters: " + jdbcUrl, e);
    }
  }

  /**
   * Extracts and normalizes the HTTP/HTTPS URL from a JDBC URL.
   *
   * <p>Automatically detects HTTPS based on port 8443 or ssl=true parameter.
   *
   * @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:")) {

View on GitHub (pinned to 12126d8942)