eclipse-vertx/vert.x · error · VertxException

Same deployable supplied more than once

Error message

Same deployable supplied more than once

What it means

When deploying multiple instances via a Supplier, each instance must be a distinct Verticle object. Vert.x collects the instances and if the resulting list size differs from the requested instance count, it means the same deployable instance was returned more than once, so it throws VertxException('Same deployable supplied more than once'). Deploying the identical verticle instance multiple times would corrupt per-instance state.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/impl/deployment/DefaultDeployment.java:54

                                             Function<Deployable, String> identifierProvider,
                                             ClassLoader tccl,
                                             Callable<? extends Deployable> supplier) throws Exception {
    int numberOfInstances = options.getInstances();
    Set<Deployable> deployables = Collections.newSetFromMap(new IdentityHashMap<>());
    for (int i = 0; i < numberOfInstances;i++) {
      Deployable deployable;
      try {
        deployable = supplier.call();
      } catch (Exception e) {
        throw e;
      }
      if (deployable == null) {
        throw new VertxException("Supplied deployable is null", true);
      }
      deployables.add(deployable);
    }
    if (deployables.size() != numberOfInstances) {
      throw new VertxException("Same deployable supplied more than once", true);
    }
    CloseableResource<WorkerPool> workerPool = null;
    ThreadingModel mode = options.getThreadingModel();
    if (mode == null) {
      mode = ThreadingModel.EVENT_LOOP;
    }
    if (mode != ThreadingModel.VIRTUAL_THREAD) {
      if (options.getWorkerPoolName() != null) {
        workerPool = vertx.createSharedWorkerPool(options.getWorkerPoolName(), options.getWorkerPoolSize(), options.getMaxWorkerExecuteTime(), options.getMaxWorkerExecuteTimeUnit());
      }
    } else {
      if (!vertx.isVirtualThreadAvailable()) {
        throw new VertxException("This Java runtime does not support virtual threads", true);
      }
    }
    ArrayList<Deployable> list = new ArrayList<>(deployables);
    return new DefaultDeployment(vertx, options, log, list, identifierProvider.apply(list.get(0)), mode, workerPool, tccl);
  }

View on GitHub (pinned to fb308bd8c3)

Solutions

  1. Make the supplier create a new Verticle instance on every invocation
  2. If you want multiple instances, use new MyVerticle() per call rather than a shared field
  3. Set instances to 1 if you truly intend to deploy a single shared object

Example fix

// before
MyVerticle v = new MyVerticle();
vertx.deployVerticle(() -> v, new DeploymentOptions().setInstances(3)); // same instance thrice
// after
vertx.deployVerticle(MyVerticle::new, new DeploymentOptions().setInstances(3)); // fresh instance each call
Defensive patterns

Strategy: validation

Validate before calling

Set<Verticle> seen = Collections.newSetFromMap(new IdentityHashMap<>());
// inside supplier:
Verticle v = create();
if (!seen.add(v)) throw new IllegalStateException("supplier reused verticle instance");

Try / catch

try {
  vertx.deployVerticle(sup, opts);
} catch (VertxException e) {
  // supplier returned the same instance for multiple instances
}

Prevention

When it happens

Trigger: deployVerticle(Supplier<Verticle>, DeploymentOptions) with setInstances(n > 1) where the supplier returns the same singleton Verticle object every time (e.g. a cached instance or a method returning a shared field).

Common situations: Returning a singleton verticle from a factory while requesting several instances; caching/memoizing the verticle construction; DI singleton scope combined with instances > 1.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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