apache/beam · error · IllegalArgumentException

Invalid scheme in JDBC URL. Expected 'http' or 'https'…

Error message

Invalid scheme in JDBC URL. Expected 'http' or 'https'. Got: 

What it means

Thrown by ClickHouseJdbcUrlParser.extractHttpUrl when the transport part of the JDBC URL begins with a scheme other than http:// or https:// (and the scheme-adding branch does not apply). Beam's ClickHouse IO supports HTTP/HTTPS transport only.

Solutions

1. Replace the scheme with http:// or https:// and use the HTTP port (8123 default, 8443 for HTTPS).
2. Remove the native 'tcp://' prefix; this connector speaks HTTP only.
3. For TLS, either use https:// explicitly or set ssl=true so http:// is upgraded.
4. Verify the server exposes the HTTP interface (http_port/https_port in config.xml).

Example fix

// before
String url = "jdbc:clickhouse:tcp://localhost:9000/default"; // native protocol
// after
String url = "jdbc:clickhouse:http://localhost:8123/default";

boolean hasHttpScheme(String jdbcUrl) {
  if (jdbcUrl == null) return false;
  String s = jdbcUrl.toLowerCase();
  int idx = s.indexOf("://");
  if (idx < 0) return false;
  int start = Math.max(0, s.lastIndexOf(":", idx - 1) + 1);
  String scheme = s.substring(start, idx);
  return scheme.equals("http") || scheme.equals("https");
}

try {
  ParsedJdbcUrl parsed = ClickHouseJdbcUrlParser.parse(jdbcUrl);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().contains("Invalid scheme in JDBC URL")) {
    throw new ConfigException("Beam ClickHouse IO only supports HTTP/HTTPS transport (ports 8123/8443), not native tcp://", e);
  }
  throw e;
}

When it happens

Trigger: Parsing a URL whose inner part after the clickhouse:/ch: prefix uses a non-HTTP scheme, e.g. 'jdbc:clickhouse:tcp://host:9000' (native protocol) or 'jdbc:ch:grpc://...'.

Common situations: Reusing URLs from the native ClickHouse JDBC driver, which defaults to tcp on port 9000; copying clickhouse-client connection strings; pointing the pipeline at a non-HTTP endpoint.

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

• Failed to decode URL parameters:
• Host cannot be empty in JDBC URL:
• Invalid JDBC URL format:
• Invalid JDBC URL format. Expected 'jdbc:clickhouse:' or…
• Invalid scheme. Expected 'http' or 'https'. Got:

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

Appendix: source

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

    // 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("://")) {
      // Extract the scheme part
      int schemeEnd = actualUrl.indexOf("://");
      String scheme = actualUrl.substring(0, schemeEnd).toLowerCase();

      if (scheme.equals("http") || scheme.equals("https")) {
        // If http:// but ssl=true detected, upgrade to https://
        if (scheme.equals("http") && useHttps) {
          actualUrl = "https://" + actualUrl.substring(schemeEnd + 3);
        }
        return actualUrl;
      } else {
        throw new IllegalArgumentException(
            "Invalid scheme in JDBC URL. Expected 'http' or 'https'. Got: " + scheme);
      }
    }

    // If URL doesn't start with http:// or https://, add the appropriate scheme
    if (actualUrl.startsWith("//")) {
      actualUrl = (useHttps ? "https:" : "http:") + actualUrl;
    } else {
      actualUrl = (useHttps ? "https://" : "http://") + actualUrl;
    }

    return actualUrl;
  }

  /**
   * Validates the URI scheme.
   *
   * @param scheme the scheme to validate

View on GitHub (pinned to 12126d8942)