What causes "Failed to decode URL parameters: " in apache/beam?

Fix malformed percent escapes in the query string (replace bare % with %25).

apache/beam · error · IllegalArgumentException

Failed to decode URL parameters:

Error message

Failed to decode URL parameters:

What it means

Thrown by ClickHouseJdbcUrlParser.parse when a URL query parameter cannot be percent-decoded (java.io.UnsupportedEncodingException caught and rethrown). The parser preserves the original jdbcUrl in the message for debugging.

Solutions

Fix malformed percent escapes in the query string (replace bare % with %25).
Percent-encode parameter values with URLEncoder.encode(value, StandardCharsets.UTF_8) before building the URL.
Pass special-character values via the Properties/DataSource API instead of embedding them in the URL.
Check whether the URL was double-encoded by an earlier processing step.

Example fix

// before
String url = "jdbc:clickhouse://host:8123/default?password=pa%ss"; // invalid percent escape
// after
String url = "jdbc:clickhouse://host:8123/default?password=" + URLEncoder.encode("pa%ss", StandardCharsets.UTF_8);

Defensive patterns

Strategy: validation

Validate before calling

boolean hasValidPercentEncoding(String query) {
  if (query == null) return true;
  java.util.regex.Matcher m = java.util.regex.Pattern.compile("%[^0-9A-Fa-f]{2}|%(?![0-9A-Fa-f]{2})").matcher(query);
  return !m.find();
}

Type guard

boolean isSafelyEncodable(String paramValue) {
  return paramValue != null && !paramValue.contains("%") && paramValue.matches("[\\x20-\\x7E]*");
}

Try / catch

try {
  ParsedJdbcUrl parsed = ClickHouseJdbcUrlParser.parse(jdbcUrl);
} catch (IllegalArgumentException e) {
  if (e.getCause() instanceof java.io.UnsupportedEncodingException) {
    throw new ConfigException("URL query parameters contain invalid percent-encoding", e);
  }
  throw e;
}

Prevention

Always URLEncoder.encode(value, StandardCharsets.UTF_8) query parameter values.
Watch for double-encoding when URLs pass through multiple processing stages.
Pass passwords/tokens with special characters via Properties or the DataSource instead of the URL.
Unit-test URL construction with values containing %, +, &, =, and spaces.

When it happens

Trigger: Parsing a jdbc:clickhouse: or jdbc:ch: URL whose query string contains malformed percent-encoding — e.g. a bare % not followed by two hex digits (password=100%) — or whose parameter decoding fails on the charset.

Common situations: Double-encoding when the URL was already decoded once; passwords/tokens containing % pasted verbatim; older tooling emitting non-UTF-8 percent escapes.

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.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

Appendix: source

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

    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:")) {
      urlWithoutJdbc = jdbcUrl.substring(5);
    }

View on GitHub (pinned to 12126d8942)