eclipse-vertx/vert.x · error · IllegalArgumentException

blockedThreadCheckInterval must be > 0

Error message

blockedThreadCheckInterval must be > 0

What it means

VertxOptions.setBlockedThreadCheckInterval rejects any value below 1 with an IllegalArgumentException. The blocked-thread-check interval controls how often Vert.x's checker scans for event-loop threads blocked longer than maxEventLoopExecuteTime; a zero or negative period is meaningless because the check would never run or would run with invalid scheduling semantics. The library throws eagerly at option-setting time so misconfiguration fails fast instead of producing a silently broken blocked-thread detector.

Source

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

   * The default value of {@link VertxOptions#setBlockedThreadCheckIntervalUnit blockedThreadCheckIntervalUnit} is {@link TimeUnit#MILLISECONDS}.
   *
   * @return the value of blocked thread check period, in {@link VertxOptions#setBlockedThreadCheckIntervalUnit blockedThreadCheckIntervalUnit}.
   */
  public long getBlockedThreadCheckInterval() {
    return blockedThreadCheckInterval;
  }

  /**
   * Sets the value of blocked thread check period, in {@link VertxOptions#setBlockedThreadCheckIntervalUnit blockedThreadCheckIntervalUnit}.
   * <p>
   * The default value of {@link VertxOptions#setBlockedThreadCheckIntervalUnit blockedThreadCheckIntervalUnit} is {@link TimeUnit#MILLISECONDS}
   *
   * @param blockedThreadCheckInterval the value of blocked thread check period, in {@link VertxOptions#setBlockedThreadCheckIntervalUnit blockedThreadCheckIntervalUnit}.
   * @return a reference to this, so the API can be used fluently
   */
  public VertxOptions setBlockedThreadCheckInterval(long blockedThreadCheckInterval) {
    if (blockedThreadCheckInterval < 1) {
      throw new IllegalArgumentException("blockedThreadCheckInterval must be > 0");
    }
    this.blockedThreadCheckInterval = blockedThreadCheckInterval;
    return this;
  }

  /**
   * Get the value of max event loop execute time, in {@link VertxOptions#setMaxEventLoopExecuteTimeUnit maxEventLoopExecuteTimeUnit}.
   * <p>
   * Vert.x will automatically log a warning if it detects that event loop threads haven't returned within this time.
   * <p>
   * This can be used to detect where the user is blocking an event loop thread, contrary to the Golden Rule of the
   * holy Event Loop.
   * <p>
   * 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() {

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass a positive value, e.g. setBlockedThreadCheckInterval(1000) (milliseconds by default).
2. If building from JSON, ensure the blockedThreadCheckInterval key is present and >= 1, or omit it to keep the default (1000 ms).
3. Clamp user-supplied config before calling the setter: options.setBlockedThreadCheckInterval(Math.max(1, configured)).

Example fix

// before
new VertxOptions().setBlockedThreadCheckInterval(0);
// after
new VertxOptions().setBlockedThreadCheckInterval(1000); // 1s default-like period

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

try {
  options.setBlockedThreadCheckInterval(interval);
} catch (IllegalArgumentException e) {
  log.warn("Invalid blockedThreadCheckInterval {}, using default 1000", interval);
  options.setBlockedThreadCheckInterval(1000);
}

When it happens

Trigger: Calling new VertxOptions().setBlockedThreadCheckInterval(0) or any negative long; VertxOptions.fromJson(JsonObject) with a JSON field "blockedThreadCheckInterval" of 0 or negative.

Common situations: Copying options objects and accidentally overwriting the field with 0 as a sentinel; deserializing an incomplete config JSON where the field defaults to 0; computing the interval from an expression that evaluates to 0 (e.g. value*unit arithmetic on empty config).

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

• maxEventLoopExecuteTime 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/2bf37027afca3ca2. Report an issue: GitHub.