eclipse-vertx/vert.x · error · IllegalArgumentException

streamWriteIdleTimeout must be >= 0

Error message

streamWriteIdleTimeout must be >= 0

What it means

EndpointConfig.setWriteIdleTimeout(Duration) throws IllegalArgumentException when given a negative Duration. The write idle timeout bounds how long a stream may send no data before being treated as idle; only null (disabled) or non-negative durations are accepted.

Source

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

  }

  /**
   * @return the read idle timeout applied to each stream
   */
  public Duration getReadIdleTimeout() {
    return readIdleTimeout;
  }

  /**
   * <p>Set the stream write 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 sent within the timeout.</p>
   *
   * @param idleTimeout  the write idle timeout
   * @return a reference to this, so the API can be used fluently
   */
  public EndpointConfig setWriteIdleTimeout(Duration idleTimeout) {
    if (idleTimeout != null && idleTimeout.isNegative()) {
      throw new IllegalArgumentException("streamWriteIdleTimeout must be >= 0");
    }
    this.writeIdleTimeout = idleTimeout;
    return this;
  }

  /**
   * @return the write idle timeout applied to each stream
   */
  public Duration getWriteIdleTimeout() {
    return writeIdleTimeout;
  }


  /**
   * @return the metrics name identifying the reported metrics.
   */
  public String getMetricsName() {
    return metricsName;

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass a non-negative Duration or null
2. Validate the Duration sign before invoking the setter
3. Fix the external config that contains the negative value

Example fix

// before
Duration t = Duration.between(start, earlierEnd); // negative
config.setWriteIdleTimeout(t);
// after
Duration t = Duration.between(earlierEnd, start);
config.setWriteIdleTimeout(t.isNegative() ? null : t);

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

boolean isUsableTimeout(Duration d) { return d == null || d.compareTo(Duration.ZERO) >= 0; }

When it happens

Trigger: Calling setWriteIdleTimeout(Duration.ofMillis(-1)) or passing a Duration computed to a negative value while configuring an endpoint.

Common situations: Config file/env values with negative numbers; arithmetic on Durations that yields a negative result; copy-paste mistakes where a negative offset was reused as a timeout.

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

• streamIdleTimeout must be >= 0
• streamReadIdleTimeout 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/1e015982a9d06bd4. Report an issue: GitHub.