eclipse-vertx/vert.x · error · IllegalArgumentException

streamIdleTimeout must be >= 0

Error message

streamIdleTimeout must be >= 0

What it means

EndpointConfig.setIdleTimeout(Duration) rejects a negative idle timeout with IllegalArgumentException. Idle timeout defines how long a connection/stream may stay inactive before being closed; a negative value is meaningless, so the setter validates eagerly. Null is allowed (means 'no timeout'), only negative durations throw.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/net/EndpointConfig.java:63

    this.metricsName = other.metricsName;
    this.logConfig = other.logConfig != null ? new LogConfig(other.logConfig) : null;
  }

  /**
   * @return the endpoint transport config
   */
  public abstract TransportConfig getTransportConfig();

  /**
   * Set the stream idle timeout, zero or {@code null} means don't time out.
   * This determines if a stream will timeout and be closed if no data is received nor sent within the timeout.
   *
   * @param idleTimeout  the idle timeout
   * @return a reference to this, so the API can be used fluently
   */
  public EndpointConfig setIdleTimeout(Duration idleTimeout) {
    if (idleTimeout != null && idleTimeout.isNegative()) {
      throw new IllegalArgumentException("streamIdleTimeout must be >= 0");
    }
    this.idleTimeout = idleTimeout;
    return this;
  }

  /**
   * @return the idle timeout applied to each stream
   */
  public Duration getIdleTimeout() {
    return idleTimeout;
  }

  /**
   * <p>Set the stream read idle timeout, zero or {@code null} means or null means don't time out. This determines if a
   * stream will timeout and be closed if no data is received within the timeout.</p>
   *
   * @param idleTimeout  the read idle timeout
   * @return a reference to this, so the API can be used fluently

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass a non-negative Duration or null to disable the timeout
2. Validate the configured value before calling setIdleTimeout
3. Fix the config source so it does not contain a negative duration

Example fix

// before
config.setIdleTimeout(Duration.ofSeconds(-30));
// after
config.setIdleTimeout(Duration.ofSeconds(30)); // or null to disable

if (timeout != null && timeout.isNegative()) { throw new IllegalArgumentException("idleTimeout must be >= 0"); }
config.setIdleTimeout(timeout);

boolean isValidTimeout(Duration d) { return d == null || !d.isNegative(); }

When it happens

Trigger: Calling EndpointConfig.setIdleTimeout(Duration.ofSeconds(-1)) or any Duration created from a negative value, e.g. Duration.ofMillis(-500), or a Duration computed from arithmetic that underflowed to negative.

Common situations: Reading the timeout from external config (YAML/JSON/env) that holds a negative number; subtracting two durations to compute a timeout and getting a negative result; typos like Duration.parse("-PT30S").

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

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

Related errors

• streamReadIdleTimeout must be >= 0
• streamWriteIdleTimeout must be >= 0
• keepAliveTimeout must be >= 0
• code: <statusCode> (expected: 0+)
• ${message}

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