apache/beam · error · IllegalArgumentException

JDBC URL cannot be null or empty

Error message

JDBC URL cannot be null or empty

What it means

ClickHouseJdbcUrlParser.parse validates its input before attempting URI extraction: a null or empty JDBC URL cannot yield an HTTP endpoint or database name, so it throws IllegalArgumentException immediately. This is the first guard in the parse pipeline that converts jdbc:clickhouse:... URLs into an HTTP URL, database, and properties.

Source

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

  /**
   * Parses a ClickHouse JDBC URL into its components.
   *
   * <p>Supported formats:
   *
   * <ul>
   *   <li>jdbc:clickhouse://host:port/database?param=value
   *   <li>jdbc:clickhouse:http://host:port/database?param=value
   *   <li>jdbc:clickhouse:https://host:port/database?param=value
   *   <li>jdbc:ch://host:port/database?param=value (ClickHouse JDBC driver shorthand)
   * </ul>
   *
   * @param jdbcUrl the JDBC URL to parse
   * @return ParsedJdbcUrl containing the HTTP/HTTPS URL, database, and properties
   * @throws IllegalArgumentException if the URL format is invalid
   */
  static ParsedJdbcUrl parse(String jdbcUrl) {
    if (Strings.isNullOrEmpty(jdbcUrl)) {
      throw new IllegalArgumentException("JDBC URL cannot be null or empty");
    }

    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) {

View on GitHub (pinned to 12126d8942)

Solutions

  1. Supply a non-empty JDBC URL of the form jdbc:clickhouse://host:port/database[?params]
  2. Check the pipeline option/config source that should contain the URL — it is null or empty at runtime
  3. Validate the URL before constructing the IO transform

Example fix

// before
ClickHouseIO.<Row>write(options.getJdbcUrl(), table) // getJdbcUrl() == ""
// after
ClickHouseIO.<Row>write("jdbc:clickhouse://localhost:8123/default", table)
Defensive patterns

Strategy: validation

Validate before calling

if (jdbcUrl == null || jdbcUrl.isEmpty()) {
  throw new IllegalArgumentException("jdbcUrl must be configured (jdbc:clickhouse://host:port/db)");
}
if (!jdbcUrl.startsWith("jdbc:clickhouse:")) {
  throw new IllegalArgumentException("Not a ClickHouse JDBC URL: " + jdbcUrl);
}

Type guard

static boolean isNonEmptyString(String s) {
  return s != null && !s.trim().isEmpty();
}

Try / catch

try {
  ClickHouseJdbcUrlParser.parse(jdbcUrl);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("cannot be null or empty")) { /* fail fast with config guidance */ }
  throw e;
}

Prevention

When it happens

Trigger: Calling parse(null), parse(""), or passing a URL field that was never populated — e.g., an unset pipeline option, a config object whose url property defaulted to null, or a builder where the connection string is supplied after parse is invoked.

Common situations: Missing JDBC URL in job options/environment config; pipeline options not wired to the IO writer; empty string from a templated config in CI/CD; refactors that changed the option name so the old one reads as null.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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