eclipse-vertx/vert.x · error · IllegalArgumentException

poolSize must be > 0

Error message

poolSize must be > 0

What it means

createSharedWorkerPool builds a named shared executor; its size must be at least 1 thread. A poolSize < 1 cannot form a valid ExecutorService, so Vert.x throws IllegalArgumentException immediately. This validates the pool's thread count, separate from maxExecuteTime validation.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/impl/VertxImpl.java:1106

  public WorkerExecutorImpl createSharedWorkerExecutor(String name, int poolSize) {
    return createSharedWorkerExecutor(name, poolSize, maxWorkerExecTime);
  }

  @Override
  public synchronized WorkerExecutorImpl createSharedWorkerExecutor(String name, int poolSize, long maxExecuteTime) {
    return createSharedWorkerExecutor(name, poolSize, maxExecuteTime, maxWorkerExecTimeUnit);
  }

  @Override
  public synchronized WorkerExecutorImpl createSharedWorkerExecutor(String name, int poolSize, long maxExecuteTime, TimeUnit maxExecuteTimeUnit) {
    CloseableResource<WorkerPool> sharedWorkerPool = createSharedWorkerPool(name, poolSize, maxExecuteTime, maxExecuteTimeUnit);
    sharedWorkerPool = registerResource(sharedWorkerPool);
    return new WorkerExecutorImpl(this, CleanerProvider.INSTANCE.get(), sharedWorkerPool);
  }

  public CloseableResource<WorkerPool> createSharedWorkerPool(String name, int poolSize, long maxExecuteTime, TimeUnit maxExecuteTimeUnit) {
    if (poolSize < 1) {
      throw new IllegalArgumentException("poolSize must be > 0");
    }
    if (maxExecuteTime < 1) {
      throw new IllegalArgumentException("maxExecuteTime must be > 0");
    }
    Supplier<WorkerPool> factory = () -> {
      ThreadFactory workerThreadFactory = createThreadFactory(threadFactory, checker, useDaemonThread, maxExecuteTime, maxExecuteTimeUnit, name + "-", true);
      ExecutorService workerExec = executorServiceFactory.createExecutor(workerThreadFactory, poolSize, poolSize);
      PoolMetrics<?, ?> workerMetrics = metrics != null ? metrics.createPoolMetrics("worker", name, poolSize) : null;
      return new WorkerPool(workerExec, workerMetrics);
    };
    return createSharedResource("__vertx.shared.workerPools", name, factory);
  }

  @Override
  public WorkerPool wrapWorkerPool(ExecutorService executor) {
    PoolMetrics workerMetrics = metrics != null ? metrics.createPoolMetrics( "worker", null, -1) : null;
    return new WorkerPool(executor, workerMetrics);
  }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Pass poolSize >= 1, e.g. Math.max(1, configuredSize)
2. Default unset config to a sane value (e.g. 20 or 2*availableProcessors) instead of 0
3. Fail fast at config load with validation rather than at pool creation

Example fix

// before
vertx.createSharedWorkerPool("db", cfg.getInt("poolSize", 0)); // throws
// after
int size = Math.max(1, cfg.getInt("poolSize", 20));
vertx.createSharedWorkerPool("db", size);

if (poolSize < 1) {
  throw new IllegalArgumentException("poolSize must be >= 1, got " + poolSize);
}

try {
  vertx.createSharedWorkerPool(name, poolSize);
} catch (IllegalArgumentException e) {
  // fall back to default pool size
}

When it happens

Trigger: vertx.createSharedWorkerPool(name, poolSize) or createSharedWorkerPool(name, poolSize, maxExecuteTime, unit) with poolSize 0 or negative, often from config like Runtime.getRuntime().availableProcessors() on exotic platforms or a computed value.

Common situations: availableProcessors() returning 0 in some container misconfigurations; poolSize = maxConcurrent - 1 arithmetic; unset config defaulting to 0; sharing one pool-sizing helper with different minima.

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

• maxExecuteTime must be > 0
• maxWorkerpExecuteTime must be > 0
• Can't specify < 1 instances to deploy
• workerPoolSize must be > 0
• blockedThreadCheckInterval must be > 0

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