{"record":{"id":"c50d800412ddc797","repo":"eclipse-vertx/vert.x","slug":"set-connect-handler-first","errorCode":null,"errorMessage":"Set connect handler first","messagePattern":"Set connect handler first","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/net/impl/tcp/NetServerImpl.java","lineNumber":169,"sourceCode":"  public Future<Void> shutdown(Duration timeout) {\n    ConnectionGroup group = channelGroup;\n    if (group == null) {\n      return vertx.getOrCreateContext().succeededFuture();\n    }\n    return group.shutdown(timeout);\n  }\n\n  @Override\n  public Future<NetServer> listen(SocketAddress localAddress) {\n    return listen(vertx.getOrCreateContext(), localAddress);\n  }\n\n  public Future<NetServer> listen(ContextInternal context, SocketAddress localAddress) {\n    if (localAddress == null) {\n      throw new NullPointerException(\"No null bind local address\");\n    }\n    if (handler == null) {\n      throw new IllegalStateException(\"Set connect handler first\");\n    }\n    return bind(context, localAddress).map(this);\n  }\n\n  @Override\n  public Future<NetServer> listen() {\n    return listen(config.getPort(), config.getHost());\n  }\n\n  public boolean isClosed() {\n    return !isListening();\n  }\n\n  private class NetSocketInitializer {\n\n    private final ContextInternal context;\n    private final Handler<NetSocket> connectionHandler;\n    private final Handler<Throwable> exceptionHandler;","sourceCodeStart":151,"sourceCodeEnd":187,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/net/impl/tcp/NetServerImpl.java#L151-L187","documentation":"A NetServer requires a connect handler before it can accept connections; without one, accepted sockets would have nowhere to go. listen() checks this precondition and throws IllegalStateException. Set the handler as part of server construction before binding.","triggerScenarios":"Calling any listen() overload on a NetServer whose connectHandler was never set (or was set after a previous listen attempt reset state).","commonSituations":"Creating a server purely to check port availability without wiring a handler; calling listen before configuration completes due to reordered initialization; relying on a default handler that does not exist.","solutions":["Call server.connectHandler(handler) before listen()","If the server is only used to probe a port, still provide a no-op handler, e.g. s -> {}","Reorder initialization so handler wiring precedes the listen call"],"exampleFix":"// before\nNetServer server = vertx.createNetServer();\nserver.listen(1234); // IllegalStateException\n// after\nNetServer server = vertx.createNetServer();\nserver.connectHandler(sock -> {});\nserver.listen(1234);","handlingStrategy":"validation","validationCode":"if (handler == null) throw new IllegalStateException(\"connectHandler must be set before listen\");\nserver.connectHandler(handler);\nserver.listen(port);","typeGuard":null,"tryCatchPattern":"try {\n  return server.listen(port);\n} catch (IllegalStateException e) {\n  throw new IllegalStateException(\"Server misconfigured: \" + e.getMessage(), e);\n}","preventionTips":["Always pair createNetServer() with an immediate connectHandler(...) call","Even port-probe servers need a no-op handler: s -> {}","Enforce builder-style construction so handler is required"],"tags":["vertx","net-server","illegal-state","initialization-order"],"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-14T00:17:10.932Z"}