eclipse-vertx/vert.x · error · IllegalArgumentException

maxEventLoopExecuteTime must be > 0

Error message

maxEventLoopExecuteTime must be > 0

What it means

VertxOptions.setMaxEventLoopExecuteTime throws IllegalArgumentException for any value < 1. This setting is the threshold after which an event-loop thread is considered blocked (logged/exception via the blocked-thread checker), expressed in maxEventLoopExecuteTimeUnit. A non-positive threshold would mark every task as instantly blocked or never schedule the check correctly, so Vert.x rejects it upfront.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/VertxOptions.java:297

   * The default value of {@link VertxOptions#setMaxEventLoopExecuteTimeUnit maxEventLoopExecuteTimeUnit} is {@link TimeUnit#NANOSECONDS}
   *
   * @return the value of max event loop execute time, in {@link VertxOptions#setMaxEventLoopExecuteTimeUnit maxEventLoopExecuteTimeUnit}.
   */
  public long getMaxEventLoopExecuteTime() {
    return maxEventLoopExecuteTime;
  }

  /**
   * Sets the value of max event loop execute time, in {@link VertxOptions#setMaxEventLoopExecuteTimeUnit maxEventLoopExecuteTimeUnit}.
   * <p>
   * The default value of {@link VertxOptions#setMaxEventLoopExecuteTimeUnit maxEventLoopExecuteTimeUnit}is {@link TimeUnit#NANOSECONDS}
   *
   * @param maxEventLoopExecuteTime the value of max event loop execute time, in {@link VertxOptions#setMaxEventLoopExecuteTimeUnit maxEventLoopExecuteTimeUnit}.
   * @return a reference to this, so the API can be used fluently
   */
  public VertxOptions setMaxEventLoopExecuteTime(long maxEventLoopExecuteTime) {
    if (maxEventLoopExecuteTime < 1) {
      throw new IllegalArgumentException("maxEventLoopExecuteTime must be > 0");
    }
    this.maxEventLoopExecuteTime = maxEventLoopExecuteTime;
    return this;
  }

  /**
   * Get the value of max worker execute time, in {@link VertxOptions#setMaxWorkerExecuteTimeUnit maxWorkerExecuteTimeUnit}.
   * <p>
   * Vert.x will automatically log a warning if it detects that worker threads haven't returned within this time.
   * <p>
   * This can be used to detect where the user is blocking a worker thread for too long. Although worker threads
   * can be blocked longer than event loop threads, they shouldn't be blocked for long periods of time.
   * <p>
   * The default value of {@link VertxOptions#setMaxWorkerExecuteTimeUnit maxWorkerExecuteTimeUnit} is {@link TimeUnit#NANOSECONDS}
   *
   * @return The value of max worker execute time, in {@link VertxOptions#setMaxWorkerExecuteTimeUnit maxWorkerExecuteTimeUnit}.
   */
  public long getMaxWorkerExecuteTime() {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass a positive duration, e.g. setMaxEventLoopExecuteTime(2000000000) with the default NANOSECONDS unit (2s).
2. Verify the paired unit (setMaxEventLoopExecuteTimeUnit) so the numeric value is interpreted as intended and stays >= 1.
3. Guard JSON-driven config: only apply the field when it parses to a value >= 1.

Example fix

// before
opts.setMaxEventLoopExecuteTime(0).setMaxEventLoopExecuteTimeUnit(TimeUnit.SECONDS);
// after
opts.setMaxEventLoopExecuteTime(2).setMaxEventLoopExecuteTimeUnit(TimeUnit.SECONDS);

if (maxEventLoopExecuteTime < 1) throw new IllegalArgumentException("maxEventLoopExecuteTime must be >= 1");
options.setMaxEventLoopExecuteTime(maxEventLoopExecuteTime);

try {
  options.setMaxEventLoopExecuteTime(v);
} catch (IllegalArgumentException e) {
  throw new IllegalArgumentException("config maxEventLoopExecuteTime invalid: " + e.getMessage(), e);
}

When it happens

Trigger: new VertxOptions().setMaxEventLoopExecuteTime(0) or a negative value; VertxOptions.fromJson with JSON "maxEventLoopExecuteTime" <= 0; tests like testBlockCheckExceptionTimeLimit setting it to probe the checker.

Common situations: Configuring very aggressive blocked-warning thresholds by hand and slipping in 0; unit/time arithmetic producing 0 (e.g. seconds*1000 with seconds=0); copying values from another options object that was never initialized.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• blockedThreadCheckInterval must be > 0
• maxWorkerpExecuteTime must be > 0
• internalBlockingPoolSize must be > 0
• warningExceptionTime must be > 0
• quorumSize should be >= 1

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