apache/beam · error · IllegalArgumentException

host must not be empty.

Error message

host must not be empty.

What it means

The Debezium read configuration validate() rejects an empty host because Debezium cannot establish a database connection without it. It throws IllegalArgumentException when getHost() returns an empty string.

Source

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

    @SchemaFieldDescription("Hostname of the source database.")
    public abstract String getHost();

    @SchemaFieldDescription("Port of the source database.")
    public abstract int getPort();

    @SchemaFieldDescription("Fully qualified table name included in the Debezium change stream.")
    public abstract String getTable();

    @SchemaFieldDescription(
        "Debezium connector type. Supported values: MYSQL, POSTGRES, SQLSERVER, ORACLE, and DB2.")
    public abstract @NonNull String getDatabase();

    @SchemaFieldDescription("Additional Debezium connection properties in key=value format.")
    public abstract @Nullable List<String> getDebeziumConnectionProperties();

    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

View on GitHub (pinned to 12126d8942)

Solutions

1. Set the host option to the database server hostname or IP before calling from()/expansion.
2. Check that the templated config (YAML/SQL) actually supplies the host parameter.
3. Guard empty environment-variable substitution at deploy time.
4. Run validate() yourself in a pre-flight config check to fail fast with a clear message.

Example fix

// before
DebeziumRead.getConnector("MYSQL").withPort(3306).withUsername("u").withPassword("p") // no host
// after
DebeziumRead.getConnector("MYSQL").withHost("db.example.com").withPort(3306).withUsername("u").withPassword("p")

if (host == null || host.isBlank()) throw new IllegalArgumentException("host must be set before building the Debezium read");

static boolean hasHost(DebeziumReadConfiguration c) {
  return c.getHost() != null && !c.getHost().isEmpty();
}

try {
  DebeziumReadSchemaTransformProvider.DebeziumReadConfiguration.from(host, port, user, pass, table, connector);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("host must not be empty")) {
    throw new ConfigException("Set the database host in the pipeline config");
  }
  throw e;
}

When it happens

Trigger: Building the Debezium read SchemaTransform via from(...)/builder without setting host, or setting it to ""; validate() is invoked during from().

Common situations: YAML/SQL transform configs missing the host key, environment-specific config not injected (empty env var substituted), or constructor built programmatically with the host omitted.

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

• port must be between 1 and 65535, but was .
• table must not be empty.
• Invalid Debezium connection property ''. Expected key=value
• 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/25f07cd707692f8e. Report an issue: GitHub.