apache/beam · error · IllegalArgumentException

Invalid Debezium connection property ''. Expected key=value

Error message

Invalid Debezium connection property ''. Expected key=value format.

What it means

Each entry in debeziumConnectionProperties must be in key=value format; validate() rejects null entries or strings whose first '=' is at index <= 0 (no key, or no '=' at all) with IllegalArgumentException identifying the offending property.

Source

Thrown at sdks/java/io/debezium/src/main/java/org/apache/beam/io/debezium/DebeziumReadSchemaTransformProvider.java:242

    public void validate() {
      if (getHost().isEmpty()) {
        throw new IllegalArgumentException("host must not be empty.");
      }

      if (getPort() <= 0 || getPort() > 65535) {
        throw new IllegalArgumentException(
            "port must be between 1 and 65535, but was " + getPort() + ".");
      }

      if (getTable().isEmpty()) {
        throw new IllegalArgumentException("table must not be empty.");
      }

      List<String> connectionProperties = getDebeziumConnectionProperties();
      if (connectionProperties != null) {
        for (String property : connectionProperties) {
          if (property == null || property.indexOf('=') <= 0) {
            throw new IllegalArgumentException(
                "Invalid Debezium connection property '"
                    + property
                    + "'. Expected key=value format.");
          }
        }
      }
    }

    public static Builder builder() {
      return new AutoValue_DebeziumReadSchemaTransformProvider_DebeziumReadSchemaTransformConfiguration
          .Builder();
    }

    @AutoValue.Builder
    public abstract static class Builder {
      public abstract Builder setMaxNumberOfRecords(@Nullable Integer maxNumberOfRecords);

      public abstract Builder setMaxTimeToRun(@Nullable Long maxTimeToRun);

View on GitHub (pinned to 12126d8942)

Solutions

1. Ensure every property is formatted as key=value, e.g. "snapshot.mode=when_needed".
2. Trim each entry and remove empty strings or nulls from the list before building the transform.
3. Parse properties from files using Properties.load rather than naive string splitting.
4. Validate the list in a pre-flight check: every entry contains '=' at position > 0.

Example fix

// before
props: ["snapshot.mode", "decimal.handling.mode=string"] // first entry invalid
// after
props: ["snapshot.mode=when_needed", "decimal.handling.mode=string"]

for (String p : props) {
  if (p == null || p.indexOf('=') <= 0) throw new IllegalArgumentException("Property '" + p + "' must be key=value");
}

static boolean isKeyValueProperty(String p) {
  return p != null && p.indexOf('=') > 0;
}

When it happens

Trigger: Passing entries like "snapshot.mode" (missing '='), "=value" (empty key), or null in the getDebeziumConnectionProperties() list.

Common situations: YAML lists accidentally splitting on ':' or copying driver properties in '-Dkey=value' style, trailing whitespace making key empty, or programmatic config built from a map joined incorrectly.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• host must not be empty.
• port must be between 1 and 65535, but was .
• table must not be empty.
• Unable to resolve class %s to use as Debezium connector.
• Cannot create enum from value!

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