eclipse-vertx/vert.x · error · VertxException

Supplied deployable is null

Error message

Supplied deployable is null

What it means

During deployment Vert.x calls the deployable supplier for each instance; if the supplier returns null the framework cannot deploy a non-existent verticle and throws VertxException('Supplied deployable is null'). This catches suppliers that construct a verticle but return null instead of the instance.

Source

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

public class DefaultDeployment implements Deployment {

  public static DefaultDeployment deployment(VertxImpl vertx,
                                             Logger log,
                                             DeploymentOptions options,
                                             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);

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Ensure the supplier always returns a non-null Verticle instance
2. Add an assertion/Objects.requireNonNull inside the supplier to fail with a clearer message
3. If creation can fail legitimately, throw a descriptive exception from the supplier instead of returning null

Example fix

// before
vertx.deployVerticle(() -> maybeCreateVerticle(type), opts); // returns null for unknown type
// after
vertx.deployVerticle(() -> {
  Verticle v = maybeCreateVerticle(type);
  if (v == null) throw new IllegalStateException("Unknown verticle type: " + type);
  return v;
}, opts);

Supplier<Verticle> sup = () -> {
  Verticle v = factory.create(type);
  return Objects.requireNonNull(v, "factory returned null for " + type);
};

try {
  vertx.deployVerticle(sup, opts).await();
} catch (VertxException e) {
  // inspect supplier: returned null deployable
}

When it happens

Trigger: deployVerticle(Supplier<Verticle>, DeploymentOptions) where the supplier returns null — e.g. a factory method that fails silently and returns null, or a lambda returning the result of a nullable lookup.

Common situations: Verticle factories with conditional creation paths returning null when a type isn't recognized; refactored suppliers whose return was dropped; DI frameworks returning null for missing beans.

Related errors

• Same deployable supplied more than once
• Invalid identifier: ${identifer}
• no null chunk accepted
• Timed out waiting for redeploy on failover
• This Java runtime does not support virtual threads

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