eclipse-vertx/vert.x · error · IllegalArgumentException

port must be <= 65535

Error message

port must be <= 65535

What it means

NetServerOptions.setPort(int) accepts values up to 65535; anything above throws IllegalArgumentException. Only the upper bound is checked here, so 0 and negative values (often meaning 'random/ephemeral port') are permitted.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/net/NetServerOptions.java:358

  }

  /**
   *
   * @return the port
   */
  public int getPort() {
    return port;
  }

  /**
   * Set the port
   *
   * @param port  the port
   * @return a reference to this, so the API can be used fluently
   */
  public NetServerOptions setPort(int port) {
    if (port > 65535) {
      throw new IllegalArgumentException("port must be <= 65535");
    }
    this.port = port;
    return this;
  }

  /**
   *
   * @return the host
   */
  public String getHost() {
    return host;
  }

  /**
   * Set the host
   * @param host  the host
   * @return a reference to this, so the API can be used fluently
   */

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Use a port in the valid range 0-65535
2. Validate the configured port before calling: port >= 0 && port <= 65535
3. Use 0 to let the OS pick an ephemeral port

Example fix

// before
options.setPort(80808); // > 65535
// after
options.setPort(8080);

int port = configuredPort;
if (port > 65535) {
  throw new IllegalArgumentException("port must be <= 65535");
}
options.setPort(port);

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

When it happens

Trigger: Calling setPort(65536) or higher, or a JSON server config whose port exceeds 65535 loaded via fromJson.

Common situations: Off-by-one or hexadecimal/decimal confusion producing values like 0x10000; concatenating host:port strings and parsing them back incorrectly; environment-specific configs with copied wrong ports.

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

• proxyProtocolTimeout must be >= 0
• Invalid proxy port
• keepAliveTimeout must be >= 0
• streamIdleTimeout must be >= 0
• streamReadIdleTimeout must be >= 0

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/10457f311d42d951. Report an issue: GitHub.