eclipse-vertx/vert.x · error · IllegalArgumentException

streamReadIdleTimeout must be >= 0

Error message

streamReadIdleTimeout must be >= 0

What it means

EndpointConfig.setReadIdleTimeout(Duration) throws IllegalArgumentException when given a negative Duration. The read idle timeout bounds how long a stream may receive no data before it is considered idle; negative values are invalid. Null disables the timeout.

Source

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

  }

  /**
   * @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
   */
  public EndpointConfig setReadIdleTimeout(Duration idleTimeout) {
    if (idleTimeout != null && idleTimeout.isNegative()) {
      throw new IllegalArgumentException("streamReadIdleTimeout must be >= 0");
    }
    this.readIdleTimeout = idleTimeout;
    return this;
  }

  /**
   * @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

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass a non-negative Duration or null
2. Add a guard like d == null || !d.isNegative() before calling the setter
3. Correct the config source supplying the negative value

Example fix

// before
config.setReadIdleTimeout(Duration.parse("-PT10S"));
// after
config.setReadIdleTimeout(Duration.ofSeconds(10));

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

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

When it happens

Trigger: Calling setReadIdleTimeout with a negative Duration such as Duration.ofSeconds(-5) or a negatively computed Duration passed to a client/server endpoint configuration.

Common situations: Negative timeout values read from configuration files or environment variables; misuse of Duration.between() where the arguments are reversed.

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
• 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/18dfa772f581d36a. Report an issue: GitHub.