What causes "Host cannot be empty in JDBC URL: " in apache/beam?

Add the hostname or IP between '//' and the next '/' in the JDBC URL.

apache/beam · error · IllegalArgumentException

Host cannot be empty in JDBC URL:

Error message

Host cannot be empty in JDBC URL:

What it means

Thrown by ClickHouseJdbcUrlParser.validateAndGetHost when the host extracted from the JDBC URI is null or empty (checked via Guava Strings.isNullOrEmpty). A ClickHouse JDBC connection must point at a concrete server host.

Solutions

Add the hostname or IP between '//' and the next '/' in the JDBC URL.
Check that the host config variable is set and non-empty before building the URL.
Inspect the jdbcUrl in the message to see where the authority went missing.
Use 'localhost' explicitly for local development rather than omitting the host.

Example fix

// before
String url = "jdbc:clickhouse:http:///default"; // empty host
// after
String url = "jdbc:clickhouse:http://localhost:8123/default";

Defensive patterns

Strategy: validation

Validate before calling

boolean hasHost(String jdbcUrl) {
  if (jdbcUrl == null) return false;
  try {
    String host = new java.net.URI(jdbcUrl.substring(jdbcUrl.indexOf(':') + 1)).getHost();
    return host != null && !host.isBlank();
  } catch (Exception e) { return false; }
}

Try / catch

try {
  ParsedJdbcUrl parsed = ClickHouseJdbcUrlParser.parse(jdbcUrl);
} catch (IllegalArgumentException e) {
  if (e.getMessage() != null && e.getMessage().contains("Host cannot be empty")) {
    throw new ConfigException("ClickHouse host is missing — check host config variable", e);
  }
  throw e;
}

Prevention

Fail fast on empty host config values before building the URL.
Always include an explicit host, even 'localhost'; don't rely on defaults.
Check templating output for silently dropped variables (e.g. ${HOST} unset).
Add an integration smoke test that parses the final URL in CI.

When it happens

Trigger: Parsing URLs with an empty authority, e.g. 'jdbc:clickhouse:http:///default' or 'jdbc:ch://', where nothing appears between '//' and the next '/'.

Common situations: Config where the HOST env var/property is empty so the template renders 'jdbc:ch://:8123'; templating engines silently dropping an unset variable; copy-paste losing the host part.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

   */
  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;
  }

  /**
   * Returns the port or default port based on scheme.
   *
   * @param port the port from URI (-1 if not specified)
   * @param scheme the URI scheme (http or https)
   * @return the port number
   */
  private static int getPortOrDefault(int port, String scheme) {
    if (port == -1) {
      return scheme.equals("https") ? 8443 : 8123; // Default ClickHouse ports
    }
    return port;
  }

View on GitHub (pinned to 12126d8942)