eclipse-vertx/vert.x · error · IllegalStateException

Event Bus is not started

Error message

Event Bus is not started

What it means

Most EventBus operations (consumer, localConsumer, sendOrPubInternal) require the bus to have completed its start sequence. EventBusImpl.checkStarted throws this IllegalStateException when 'started' is false, protecting against use of a bus whose internal structures are not yet initialized.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/eventbus/impl/EventBusImpl.java:427

          }
        }
      }
      return null;
    } else {
      if (metrics != null) {
        metrics.messageReceived(msg.address(), !msg.isSend(), messageLocal, 0);
      }
      return new ReplyException(ReplyFailure.NO_HANDLERS, "No handlers for address " + msg.address);
    }
  }

  protected HandlerHolder nextHandler(ConcurrentCyclicSequence<HandlerHolder> handlers, boolean messageLocal) {
    return handlers.next();
  }

  protected void checkStarted() {
    if (!started) {
      throw new IllegalStateException("Event Bus is not started");
    }
  }

  protected String generateReplyAddress() {
    return "__vertx.reply." + Long.toString(replySequence.incrementAndGet());
  }

  <T> ReplyHandler<T> createReplyHandler(MessageImpl message,
                                         boolean src,
                                         DeliveryOptions options) {
    return createReplyHandler(vertx.getOrCreateContext(), message, src,  options);
  }

  <T> ReplyHandler<T> createReplyHandler(ContextInternal context,
                                         MessageImpl message,
                                         boolean src,
                                         DeliveryOptions options) {
    long timeout = options.getSendTimeout();

View on GitHub (pinned to fb308bd8c3)

Solutions

  1. Call eventBus().start(...) and wait for the returned future before using the bus.
  2. Move bus usage into verticle.start(Promise) and complete the promise after consumers are registered.
  3. Compose on vertx.deployVerticle(...) / startup future with Futures.allSuccessful before sending messages.
  4. Verify you are not calling EventBus methods on an EventBus from a Vertx instance you constructed without finishing its start.

Example fix

// before
vertx.eventBus().consumer("addr", msg -> {}); // too early
// after
vertx.eventBus().start().onSuccess(v -> {
  vertx.eventBus().consumer("addr", msg -> {});
});
Defensive patterns

Strategy: validation

Validate before calling

// only touch the bus after startup completes
vertx.eventBus().start().compose(v -> {
  vertx.eventBus().consumer("addr", msg -> {});
  return Promise.<Void>succeededFuture().future();
});

Try / catch

try {
  bus.consumer("addr", handler);
} catch (IllegalStateException e) {
  // bus not started; defer registration until start future completes
}

Prevention

When it happens

Trigger: Registering consumers or sending messages on the event bus before vertx.eventBus().start() (or Vertx startup) has completed; using an EventBus obtained from a Vertx instance that is still initializing.

Common situations: Application code using the bus inside a Verticle's constructor or before start() completes; custom Vertx builders/graalvm init that grab the event bus too early; tests that send messages immediately after Vertx.vertx() without awaiting startup.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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