eclipse-vertx/vert.x · error · IllegalArgumentException

internalBlockingPoolSize must be > 0

Error message

internalBlockingPoolSize must be > 0

What it means

VertxOptions.setInternalBlockingPoolSize throws IllegalArgumentException if internalBlockingPoolSize < 1. The internal blocking pool executes Vert.x's own blocking operations (e.g. filesystem access); a pool size of zero or negative would leave no threads to serve these operations. Vert.x validates at set-time so the failure surfaces at configuration, not during runtime I/O.

Source

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

   * Get the value of internal blocking pool size.
   * <p>
   * Vert.x maintains a pool for internal blocking operations
   *
   * @return the value of internal blocking pool size
   */
  public int getInternalBlockingPoolSize() {
    return internalBlockingPoolSize;
  }

  /**
   * Set the value of internal blocking pool size
   *
   * @param internalBlockingPoolSize the maximumn number of threads in the internal blocking pool
   * @return a reference to this, so the API can be used fluently
   */
  public VertxOptions setInternalBlockingPoolSize(int internalBlockingPoolSize) {
    if (internalBlockingPoolSize < 1) {
      throw new IllegalArgumentException("internalBlockingPoolSize must be > 0");
    }
    this.internalBlockingPoolSize = internalBlockingPoolSize;
    return this;
  }

  /**
   * Will HA be enabled on the Vert.x instance?
   *
   * @return true if HA enabled, false otherwise
   */
  public boolean isHAEnabled() {
    return haEnabled;
  }

  /**
   * Set whether HA will be enabled on the Vert.x instance.
   *
   * @param haEnabled true if enabled, false if not.

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass a positive size, e.g. setInternalBlockingPoolSize(20) (the default).
2. Fix the config source so the value resolves to >= 1 (e.g. default unset env vars to 20).
3. Clamp before setting: options.setInternalBlockingPoolSize(Math.max(1, configured)).

Example fix

// before
opts.setInternalBlockingPoolSize(Integer.parseInt(System.getenv("IBP_SIZE")));
// after
int n = Integer.parseInt(System.getenv().getOrDefault("IBP_SIZE", "20"));
opts.setInternalBlockingPoolSize(Math.max(1, n));

int size = configured == null ? 20 : configured;
if (size < 1) size = 20; // or fail with a clear message
options.setInternalBlockingPoolSize(size);

try {
  options.setInternalBlockingPoolSize(size);
} catch (IllegalArgumentException e) {
  throw new IllegalStateException("internalBlockingPoolSize must be >= 1, got " + size, e);
}

When it happens

Trigger: new VertxOptions().setInternalBlockingPoolSize(0) or negative; VertxOptions.fromJson with "internalBlockingPoolSize" <= 0 (e.g. an env-driven config resolving to 0).

Common situations: Sizing the pool from a CPU-count or env-var expression that evaluates to 0 (unset env parsed as 0); copying a config template with a placeholder 0; confusing this pool with the user worker pool and passing a pool-size of 0 to disable it.

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