What causes "Invalid scheme. Expected 'http' or 'https'. Got: " in apache/beam?

Use 'http://' or 'https://' as the protocol in the JDBC URL.

apache/beam · error · IllegalArgumentException

Invalid scheme. Expected 'http' or 'https'. Got:

Error message

Invalid scheme. Expected 'http' or 'https'. Got:

What it means

Thrown by ClickHouseJdbcUrlParser.validateScheme when the URI scheme extracted from the JDBC URL is neither 'http' nor 'https' (or is null). A final check ensuring the connection target uses a transport this connector implements.

Solutions

Use 'http://' or 'https://' as the protocol in the JDBC URL.
Check that the configured URL template actually interpolates the scheme variable (no empty ${SCHEME}).
Compare against the message's scheme value to see what was actually parsed.
Confirm the ClickHouse server's HTTP/HTTPS port is used.

Example fix

// before
String url = "jdbc:clickhouse:ftp://host/path";
// after
String url = "jdbc:clickhouse:https://host:8443/path";

Defensive patterns

Strategy: validation

Validate before calling

boolean schemeIsHttpOrHttps(String url) {
  if (url == null) return false;
  try {
    String scheme = new java.net.URI(url).getScheme();
    return "http".equals(scheme) || "https".equals(scheme);
  } catch (java.net.URISyntaxException e) { return false; }
}

Try / catch

try {
  ParsedJdbcUrl parsed = ClickHouseJdbcUrlParser.parse(jdbcUrl);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Invalid scheme.")) {
    throw new ConfigException("ClickHouse JDBC URL must use http or https scheme: " + jdbcUrl, e);
  }
  throw e;
}

Prevention

Ensure config templates always interpolate a non-empty scheme variable.
Default to https:// in production configurations.
Validate the fully-rendered URL at configuration load time, not at write time.
Log the rendered URL (minus credentials) once at startup to catch scheme drift early.

When it happens

Trigger: Parsing a URL whose protocol is not http/https (e.g. 'jdbc:clickhouse:ftp://host/path') or a malformed/relative URI whose getScheme() returns null.

Common situations: URLs copied from other tooling with custom schemes; truncated URLs losing the scheme; config templates where the protocol variable interpolated empty.

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/362450ab107be9de. Report an issue: GitHub.

Appendix: source

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

    // 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
   * @throws IllegalArgumentException if scheme is invalid
   */
  private static void validateScheme(String scheme) {
    if (scheme == null || (!scheme.equals("http") && !scheme.equals("https"))) {
      throw new IllegalArgumentException(
          "Invalid scheme. Expected 'http' or 'https'. Got: " + scheme);
    }
  }

  /**
   * Validates and returns the host from the URI.
   *
   * @param host the host to validate
   * @param jdbcUrl the original JDBC URL (for error reporting)
   * @return the validated host
   * @throws IllegalArgumentException if host is invalid
   */
  private static String validateAndGetHost(String host, String jdbcUrl) {
    if (Strings.isNullOrEmpty(host)) {
      throw new IllegalArgumentException("Host cannot be empty in JDBC URL: " + jdbcUrl);
    }
    return host;
  }

View on GitHub (pinned to 12126d8942)