eclipse-vertx/vert.x · error · IllegalArgumentException

Can't specify < 1 instances to deploy

Error message

Can't specify < 1 instances to deploy

What it means

When deploying verticles you can request multiple instances via DeploymentOptions.setInstances(n); Vert.x requires at least 1. Passing 0 or a negative count throws IllegalArgumentException synchronously from deployVerticle before any deployment begins.

Source

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

  @Override
  public Future<String> deployVerticle(Supplier<? extends Deployable> supplier, DeploymentOptions options) {
    Callable<? extends Deployable> adapter = supplier::get;
    return deployVerticle(adapter, options).map(DeploymentContext::id);
  }

  private Future<DeploymentContext> deployVerticle(Callable<? extends Deployable> supplier, DeploymentOptions options) {
    boolean closed;
    synchronized (this) {
      closed = this.closed;
    }
    if (closed) {
      // If we are closed use a context less future
      return Future.failedFuture("Vert.x closed");
    } else {
      ContextInternal currentContext = getOrCreateContext();
      if (options.getInstances() < 1) {
        throw new IllegalArgumentException("Can't specify < 1 instances to deploy");
      }
      ClassLoader cl = options.getClassLoader();
      if (cl == null) {
        cl = Thread.currentThread().getContextClassLoader();
        if (cl == null) {
          cl = getClass().getClassLoader();
        }
      }
      Deployment deployment;
      try {
        deployment = DefaultDeployment.deployment(this, log, options, v -> "java:" + v.getClass().getName(), cl, supplier);
      } catch (Exception e) {
        return currentContext.failedFuture(e);
      }

      // NEED TO SOLVE THIS

      return deploymentManager.deploy(currentContext.deploymentID(), currentContext, deployment);

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Call options.setInstances(Math.max(1, desiredInstances))
2. Ensure config-derived instance counts default to 1 (or another positive value) when unset
3. Reject invalid configuration at startup with a clear message before deploying

Example fix

// before
opts.setInstances(cfg.getInteger("instances", 0)); // 0 -> IllegalArgumentException
// after
opts.setInstances(Math.max(1, cfg.getInteger("instances", 1)));

DeploymentOptions opts = new DeploymentOptions();
if (opts.getInstances() < 1) {
  opts.setInstances(1);
}

try {
  vertx.deployVerticle(supplier, opts);
} catch (IllegalArgumentException e) {
  // log config error: instances must be >= 1
}

When it happens

Trigger: vertx.deployVerticle(...) with DeploymentOptions whose getInstances() < 1 — e.g. setInstances(0), or instances loaded from config/environment as an unset default 0.

Common situations: Instances count read from a properties/env config where 0 was meant as 'use default'; arithmetic like parallelism - 1 yielding 0 on single-core machines; copy-paste of setInstances(0) in test scaffolding.

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

• This Java runtime does not support virtual threads
• poolSize must be > 0
• maxExecuteTime must be > 0
• 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/8239774c18d87c3e. Report an issue: GitHub.