{"record":{"id":"f7ec81b5d7f64bc8","repo":"eclipse-vertx/vert.x","slug":"set-request-or-websocket-handler-first","errorCode":null,"errorMessage":"Set request or WebSocket handler first","messagePattern":"Set request or WebSocket handler first","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/http/impl/tcp/TcpHttpServer.java","lineNumber":197,"sourceCode":"\n  @Override\n  public Future<HttpServer> listen() {\n    return listen(vertx.getOrCreateContext());\n  }\n\n  @Override\n  public Future<HttpServer> listen(SocketAddress address) {\n    return listen(vertx.getOrCreateContext(), address);\n  }\n\n  @Override\n  public Future<HttpServer> listen(ContextInternal context) {\n    return listen(context, SocketAddress.inetSocketAddress(config.getTcpPort(), config.getTcpHost()));\n  }\n\n  public synchronized Future<HttpServer> listen(ContextInternal context, SocketAddress address) {\n    if (requestHandler == null && webSocketHandler == null && webSocketHandhakeHandler == null) {\n      throw new IllegalStateException(\"Set request or WebSocket handler first\");\n    }\n    if (tcpServer != null) {\n      throw new IllegalStateException();\n    }\n    HttpServerConfig config = this.config;\n    ContextInternal listenContext;\n    // Not sure of this\n    if (context.isEventLoopContext()) {\n      listenContext = context;\n    } else {\n      listenContext = context.toBuilder()\n        .withThreadingModel(ThreadingModel.EVENT_LOOP)\n        .build();\n    }\n    CompressionConfig compression = config.getCompressionConfig();\n    ServerSSLOptions sslOptions = configureSSLOptions(config, this.sslOptions);\n    TcpServerConfig tcpConfig = new TcpServerConfig(config.getTcpConfig())\n      .setSsl(ssl);","sourceCodeStart":179,"sourceCodeEnd":215,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/impl/tcp/TcpHttpServer.java#L179-L215","documentation":"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.","triggerScenarios":"Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/tcp/TcpHttpServer.java:197 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Call requestHandler(...) or webSocketHandler(...) before listen()","Move the listen() call after all handler wiring in startup code"],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}