apache/beam · error · IllegalArgumentException

Properties cannot be null

Error message

Properties cannot be null

What it means

ClickHouseIO.Write.withProperties accepts extra JDBC connection properties to pass to the ClickHouse client. Because a null Properties object cannot be merged or conflict-checked against properties already parsed from the JDBC URL, the builder throws IllegalArgumentException immediately when null is supplied.

Source

Thrown at sdks/java/io/clickhouse/src/main/java/org/apache/beam/sdk/io/clickhouse/ClickHouseIO.java:418

    /**
     * Set connection properties (user, password, etc.).
     *
     * <p><b>Important:</b> If using the deprecated JDBC URL-based {@link #write(String, String)}
     * method, this will fail if any properties specified here conflict with properties already
     * extracted from the JDBC URL. This prevents accidental property conflicts.
     *
     * <p>For the new API {@link #write(String, String, String)}, properties can be set freely since
     * there are no URL-embedded properties to conflict with.
     *
     * @param properties connection properties
     * @return a {@link PTransform} writing data to ClickHouse
     * @throws IllegalArgumentException if properties is null or if any property conflicts with
     *     existing properties (e.g., from JDBC URL)
     */
    public Write<T> withProperties(Properties properties) {
      if (properties == null) {
        throw new IllegalArgumentException("Properties cannot be null");
      }

      // Check for conflicts with existing properties
      Properties existing = properties();
      for (String key : properties.stringPropertyNames()) {
        if (existing.containsKey(key)) {
          String existingValue = existing.getProperty(key);
          String newValue = properties.getProperty(key);
          if (!existingValue.equals(newValue)) {
            throw new IllegalArgumentException(
                String.format(
                    "Property conflict: '%s' is already set to '%s' (likely from JDBC URL), "
                        + "but attempting to set it to '%s'. "
                        + "Please use either JDBC URL properties OR withProperties(), not both for the same keys.",
                    key, existingValue, newValue));
          }
        }
      }

View on GitHub (pinned to 12126d8942)

Solutions

1. Only call withProperties when the Properties object is non-null
2. Initialize with new Properties() instead of null as the default
3. Use an empty Properties object — withProperties accepts an empty set safely

Example fix

// before
if (userProps != null) writer = writer.withProperties(userProps); // called unconditionally elsewhere
// after
writer = writer.withProperties(userProps == null ? new Properties() : userProps);

if (props == null) {
  props = new Properties(); // or skip the withProperties call
}

static Properties nonNullProps(Properties p) {
  return p == null ? new Properties() : p;
}

try {
  writer = writer.withProperties(props);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("Properties cannot be null")) { writer = writer.withProperties(new Properties()); }
  else throw e;
}

When it happens

Trigger: Calling writer.withProperties(null) directly, or forwarding a Properties field/variable that was never initialized (e.g., a method parameter that defaults to null when no user properties are configured).

Common situations: Wiring user-supplied connection properties from config where the absence of settings yields null; refactors that changed a default Properties instance into null; calling withProperties unconditionally even when the user supplied none.

Related errors

• Property conflict: '%s' is already set to '%s' (likely from
• JDBC URL cannot be null or empty
• Config class must be not null!
• Failed to write to ClickHouse after retries
• Failed to get table schema for table:

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