eclipse-vertx/vert.x · error · IllegalArgumentException

Invalid proxy port

Error message

Invalid proxy port 

What it means

Configuration validation in ProxyOptions.setPort: the proxy port must be within the valid range 0-65535. The offending port value is appended to the message; out-of-range ports cannot be used to reach the proxy and are rejected up front.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/net/ProxyOptions.java:146

  /**
   * Get proxy port.
   *
   * @return  proxy port
   */
  public int getPort() {
    return port;
  }

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

  /**
   * Get proxy username.
   *
   * @return  proxy username
   */
  public String getUsername() {
    return username;
  }

  /**
   * Set proxy username.
   *
   * @param username the proxy username

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Use a valid proxy port (commonly 3128, 8080, 1080)
2. Validate proxy configuration from JSON before constructing ProxyOptions

Example fix

// before
new ProxyOptions().setPort(-1); // throws
// after
new ProxyOptions().setPort(3128);

int port = configuredProxyPort;
if (port < 0 || port > 65535) {
  throw new IllegalArgumentException("proxy port must be in 0..65535");
}
proxyOptions.setPort(port);

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

try {
  proxyOptions.setPort(port);
} catch (IllegalArgumentException e) {
  log.error("Invalid proxy port {} - expected 0..65535", port, e);
  throw e;
}

When it happens

Trigger: Calling setPort(-1) (e.g. reusing the 'unset' convention from other options classes) or setPort(70000), or a JSON proxy config via fromJson with an out-of-range port.

Common situations: Reusing -1 as a 'default/unset' marker that other Vert.x setters accept; parsing 'host:port' strings where the port token is malformed; merged/partial configs supplying placeholder 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

• port must be <= 65535
• keepAliveTimeout must be >= 0
• streamIdleTimeout must be >= 0
• streamReadIdleTimeout must be >= 0
• streamWriteIdleTimeout must be >= 0

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