eclipse-vertx/vert.x · error · IllegalStateException

Set request or WebSocket handler first

Error message

Set request or WebSocket handler first

What it means

Lifecycle guard in TcpHttpServer.listen: the server was asked to listen before any request handler or WebSocket handler was registered. Starting to accept connections with nothing to dispatch requests to is a configuration mistake, so listen fails fast instead of serving dead connections.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/tcp/TcpHttpServer.java:197

  @Override
  public Future<HttpServer> listen() {
    return listen(vertx.getOrCreateContext());
  }

  @Override
  public Future<HttpServer> listen(SocketAddress address) {
    return listen(vertx.getOrCreateContext(), address);
  }

  @Override
  public Future<HttpServer> listen(ContextInternal context) {
    return listen(context, SocketAddress.inetSocketAddress(config.getTcpPort(), config.getTcpHost()));
  }

  public synchronized Future<HttpServer> listen(ContextInternal context, SocketAddress address) {
    if (requestHandler == null && webSocketHandler == null && webSocketHandhakeHandler == null) {
      throw new IllegalStateException("Set request or WebSocket handler first");
    }
    if (tcpServer != null) {
      throw new IllegalStateException();
    }
    HttpServerConfig config = this.config;
    ContextInternal listenContext;
    // Not sure of this
    if (context.isEventLoopContext()) {
      listenContext = context;
    } else {
      listenContext = context.toBuilder()
        .withThreadingModel(ThreadingModel.EVENT_LOOP)
        .build();
    }
    CompressionConfig compression = config.getCompressionConfig();
    ServerSSLOptions sslOptions = configureSSLOptions(config, this.sslOptions);
    TcpServerConfig tcpConfig = new TcpServerConfig(config.getTcpConfig())
      .setSsl(ssl);

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Call requestHandler(...) or webSocketHandler(...) before listen()
2. Move the listen() call after all handler wiring in startup code

When it happens

Trigger: Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/tcp/TcpHttpServer.java:197 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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