apache/beam · error · IllegalArgumentException

port must be between 1 and 65535, but was .

Error message

port must be between 1 and 65535, but was .

What it means

Validation guard in DebeziumReadSchemaTransformProvider's configuration: the port field is checked against the valid TCP range and must be an integer between 1 and 65535. An out-of-range or unparsable port supplied in the transform config causes validate() (invoked via from()) to raise this error before any connection is attempted.

Source

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

    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
                    + "'. Expected key=value format.");
          }
        }
      }

View on GitHub (pinned to 12126d8942)

Solutions

1. Set port to the database's actual listening port (e.g. 3306 MySQL, 5432 PostgreSQL, 1433 SQL Server).
2. Check templated configs for unreplaced placeholders resulting in 0.
3. Clamp/validate the port at config load time before constructing the transform.
4. Confirm no trailing characters are parsed into the port value.

Example fix

// before
.withPort(Integer.parseInt(System.getenv("DB_PORT"))) // unset -> 0
// after
int port = Integer.parseInt(Optional.ofNullable(System.getenv("DB_PORT")).orElse("3306"));
if (port <= 0 || port > 65535) throw new IllegalArgumentException("bad port");
.withPort(port)

int p = Integer.parseInt(portRaw.trim());
if (p <= 0 || p > 65535) throw new IllegalArgumentException("port must be between 1 and 65535, but was " + p);

static boolean validPort(int port) {
  return port > 0 && port <= 65535;
}

When it happens

Trigger: Providing port <= 0 or > 65535 in the Debezium read configuration; commonly the port field left at 0 because the option was never set.

Common situations: Config placeholder not replaced (port=0), typo like 65356 instead of 6536/3306, or unit confusion (passing milliseconds or a port read from the wrong config key).

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• host must not be empty.
• 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/f09925745ecd0e80. Report an issue: GitHub.