eclipse-vertx/vert.x · error · IllegalArgumentException

Timeout must be >= 0

Error message

Timeout  must be >= 0

What it means

ShutdownEvent validates its timeout: a negative Duration is rejected with IllegalArgumentException ('Timeout X must be >= 0'). A shutdown timeout defines how long to wait for graceful connection close, so negative values are meaningless. Zero is allowed (immediate shutdown).

Source

Thrown at vertx-core/src/main/java/io/vertx/core/net/impl/ShutdownEvent.java:29

package io.vertx.core.net.impl;

import java.time.Duration;
import java.util.concurrent.TimeUnit;

/**
 * Signals that a resource will be closed within a certain amount of time.
 */
public class ShutdownEvent {

  private final Duration timeout;

  public ShutdownEvent(long timeout, TimeUnit timeUnit) {
    this(Duration.ofMillis(timeUnit.toMillis(timeout)));
  }

  public ShutdownEvent(Duration timeout) {
    if (timeout.isNegative()) {
      throw new IllegalArgumentException("Timeout " + timeout + " must be >= 0");
    }
    this.timeout = timeout;
  }

  public Duration timeout() {
    return timeout;
  }
}

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Clamp the timeout before constructing: Duration.ofMillis(Math.max(0, millis))
2. Treat negative configured values as 'no timeout' and use a large/default duration instead
3. Fix config files that use -1 as a sentinel for 'disabled'

Example fix

// before
long timeout = config.getLong("shutdownTimeout", -1L);
vertx.close(new ShutdownEvent(timeout, TimeUnit.MILLISECONDS));
// after
long timeout = config.getLong("shutdownTimeout", 0L);
vertx.close(new ShutdownEvent(Math.max(0, timeout), TimeUnit.MILLISECONDS));

if (timeout < 0) throw new IllegalArgumentException("shutdown timeout must be >= 0, got " + timeout);
new ShutdownEvent(timeout, TimeUnit.MILLISECONDS);

try {
  new ShutdownEvent(cfgTimeout, TimeUnit.MILLISECONDS);
} catch (IllegalArgumentException e) {
  // log and clamp to 0 or a default
}

When it happens

Trigger: Constructing new ShutdownEvent(-1, TimeUnit.SECONDS) or new ShutdownEvent(Duration.ofSeconds(-1)), or passing a negative computed duration from config.

Common situations: Config value parsed as negative (e.g. '-1' meaning 'disabled' in the user's config convention), or arithmetic on durations that underflows (a - now).

Understand the failure class

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

Related errors

• Timeout must be >= 0
• Result is already complete
• Cannot truncate file to size < 0
• keepAliveTimeout must be >= 0
• maxPoolSize must be > 0

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