eclipse-vertx/vert.x · error · IllegalArgumentException

proxyProtocolTimeout must be >= 0

Error message

proxyProtocolTimeout must be >= 0

What it means

NetServerOptions.setProxyProtocolTimeout(long) requires a non-negative timeout in milliseconds (0 typically disables it); negative values throw IllegalArgumentException. This timeout governs how long the server waits for a complete PROXY protocol header.

Source

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

    return this;
  }

  /**
   * @return the Proxy protocol timeout, in time unit specified by {@link #getProxyProtocolTimeoutUnit()}.
   */
  public long getProxyProtocolTimeout() {
    return proxyProtocolTimeout;
  }

  /**
   * Set the Proxy protocol timeout, default time unit is seconds.
   *
   * @param proxyProtocolTimeout the Proxy protocol timeout to set
   * @return a reference to this, so the API can be used fluently
   */
  public NetServerOptions setProxyProtocolTimeout(long proxyProtocolTimeout) {
    if (proxyProtocolTimeout < 0) {
      throw new IllegalArgumentException("proxyProtocolTimeout must be >= 0");
    }
    this.proxyProtocolTimeout = proxyProtocolTimeout;
    return this;
  }

  /**
   * Set the Proxy protocol timeout unit. If not specified, default is seconds.
   *
   * @param proxyProtocolTimeoutUnit specify time unit.
   * @return a reference to this, so the API can be used fluently
   */
  public NetServerOptions setProxyProtocolTimeoutUnit(TimeUnit proxyProtocolTimeoutUnit) {
    this.proxyProtocolTimeoutUnit = proxyProtocolTimeoutUnit;
    return this;
  }

  /**
   * @return the Proxy protocol timeout unit.

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Use 0 to disable the timeout, or a positive millisecond value
2. Clamp: Math.max(0, timeout) before calling
3. Fix the JSON config value to be >= 0

Example fix

// before
options.setProxyProtocolTimeout(-10);
// after
options.setProxyProtocolTimeout(3000); // 3s, or 0 to disable

long t = configuredTimeout;
if (t < 0) {
  throw new IllegalArgumentException("proxyProtocolTimeout must be >= 0");
}
options.setProxyProtocolTimeout(t);

boolean isNonNegative(long v) { return v >= 0; }

When it happens

Trigger: Calling setProxyProtocolTimeout(-1) or lower, or a JSON config with a negative proxyProtocolTimeout processed via fromJson.

Common situations: Negative sentinel from config meaning 'disabled' (should be 0 instead); sign errors in computed durations; template configs left with negative defaults.

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.

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

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/bfc1a6e9593e0fe3. Report an issue: GitHub.