{"record":{"id":"2d9527f0cfff1f8e","repo":"eclipse-vertx/vert.x","slug":"please-set-handler-before-server-is-listening","errorCode":null,"errorMessage":"Please set handler before server is listening","messagePattern":"Please set handler before server is listening","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/http/impl/tcp/TcpHttpServer.java","lineNumber":119,"sourceCode":"    }\n    return s.updateTrafficShapingOptions(options);\n  }\n\n  @Override\n  public synchronized int actualPort() {\n    NetServer s = tcpServer;\n    return s != null ? s.actualPort() : 0;\n  }\n\n  @Override\n  public HttpServerMetrics<?, ?> getMetrics() {\n    return httpMetrics;\n  }\n\n  @Override\n  public synchronized HttpServer requestHandler(Handler<HttpServerRequest> handler) {\n    if (isListening()) {\n      throw new IllegalStateException(\"Please set handler before server is listening\");\n    }\n    requestHandler = handler;\n    return this;\n  }\n\n  @Override\n  public synchronized HttpServer webSocketHandler(Handler<ServerWebSocket> handler) {\n    if (isListening()) {\n      throw new IllegalStateException(\"Please set handler before server is listening\");\n    }\n    webSocketHandler = handler;\n    return this;\n  }\n\n  @Override\n  public HttpServer webSocketHandshakeHandler(Handler<ServerWebSocketHandshake> handler) {\n    if (isListening()) {\n      throw new IllegalStateException(\"Please set handler before server is listening\");","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/impl/tcp/TcpHttpServer.java#L101-L137","documentation":"TcpHttpServer.requestHandler() throws IllegalStateException when the server is already listening. Request routing is captured when the server starts, so Vert.x forbids changing it after listen() to guarantee consistent handling of in-flight connections.","triggerScenarios":"Calling requestHandler(Handler<HttpServerRequest>) on a TcpHttpServer whose isListening() is true (listen() called previously).","commonSituations":"Setting the request handler after server startup in dependency-injection wiring; hot-swapping routing logic at runtime without a restart; double-initialization where the handler is set both before and after listen().","solutions":["Set requestHandler() before calling listen()","Reorder initialization so handler wiring precedes listen()","For dynamic routing, register a stable dispatcher handler up front and route internally","Check isListening() before setting the handler to fail fast with your own message"],"exampleFix":"// before\nserver.listen(port);\nserver.requestHandler(req -> { ... }); // throws\n// after\nserver.requestHandler(req -> { ... });\nserver.listen(port);","handlingStrategy":"validation","validationCode":"if (server.isListening()) { throw new IllegalStateException(\"Cannot change requestHandler after listen\"); }\nserver.requestHandler(req -> { ... });","typeGuard":null,"tryCatchPattern":"try { server.requestHandler(h); } catch (IllegalStateException e) { log.error(\"requestHandler must be set before listen()\", e); }","preventionTips":["Always set requestHandler before listen()","Use a single setup method that configures handlers then listens","For dynamic routing, use a stable dispatcher installed pre-listen"],"tags":["http","lifecycle","routing"],"backgroundTag":"invalid-state-transition","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"}