eclipse-vertx/vert.x · error · IllegalArgumentException

warningExceptionTime must be > 0

Error message

warningExceptionTime must be > 0

What it means

VertxOptions.setWarningExceptionTime throws IllegalArgumentException for values < 1. This is the interval after which a still-blocked thread escalates from a warning-level log to an exception-level log in the blocked-thread checker, expressed in warningExceptionTimeUnit. Non-positive values are rejected because the escalation timer would fire immediately or never, corrupting the checker's log semantics.

Source

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

   * <p>
   * The default value of {@link VertxOptions#setWarningExceptionTimeUnit warningExceptionTimeUnit} is {@link TimeUnit#NANOSECONDS}
   *
   * @return the warning exception time threshold
   */
  public long getWarningExceptionTime() {
    return warningExceptionTime;
  }

  /**
   * Set the threshold value above this, the blocked warning contains a stack trace. in {@link VertxOptions#setWarningExceptionTimeUnit warningExceptionTimeUnit}.
   * The default value of {@link VertxOptions#setWarningExceptionTimeUnit warningExceptionTimeUnit} is {@link TimeUnit#NANOSECONDS}
   *
   * @param warningExceptionTime
   * @return a reference to this, so the API can be used fluently
   */
  public VertxOptions setWarningExceptionTime(long warningExceptionTime) {
    if (warningExceptionTime < 1) {
      throw new IllegalArgumentException("warningExceptionTime must be > 0");
    }
    this.warningExceptionTime = warningExceptionTime;
    return this;
  }

  /**
   * @return the event bus option to configure the event bus communication (host, port, ssl...)
   */
  public EventBusOptions getEventBusOptions() {
    return eventBusOptions;
  }

  /**
   * Sets the event bus configuration to configure the host, port, ssl...
   *
   * @param options the event bus options
   * @return a reference to this, so the API can be used fluently
   */

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass a positive value, e.g. setWarningExceptionTime(5000) with the default NANOSECONDS semantics matching maxWorkerExecuteTime.
2. Keep warningExceptionTime >= maxWorkerExecuteTime/maxEventLoopExecuteTime so escalation happens after the initial blocked threshold.
3. If you need to suppress escalation logging, configure the blocked-thread checker's log level or a custom handler instead of zeroing this value.

Example fix

// before
opts.setWarningExceptionTime(0); // intent: never escalate
// after
opts.setWarningExceptionTime(5_000_000_000L); // 5s escalation with default ns unit

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

try {
  options.setWarningExceptionTime(v);
} catch (IllegalArgumentException e) {
  log.warn("Invalid warningExceptionTime, using 5s");
  options.setWarningExceptionTime(5_000_000_000L);
}

When it happens

Trigger: new VertxOptions().setWarningExceptionTime(0) or negative; VertxOptions.fromJson with "warningExceptionTime" <= 0; blocked-checker tests (testBlockCheckExceptionTimeLimit, testBlockCheckWorker, testBlockCheckExecuteBlocking, testCustomThreadBlockedHandler) tuning escalation timing.

Common situations: Misreading the field as 'time after which to warn' and setting 0 to disable warnings; unit mixups (writing a seconds value while the unit is nanoseconds is fine, but writing 0 to 'disable' is not); copying options where warningExceptionTime was zeroed.

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
• maxEventLoopExecuteTime must be > 0
• maxWorkerpExecuteTime must be > 0
• internalBlockingPoolSize must be > 0
• quorumSize should be >= 1

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