{"record":{"id":"c96ed9b993549d9b","repo":"eclipse-vertx/vert.x","slug":"listen-already-called","errorCode":null,"errorMessage":"Listen already called","messagePattern":"Listen already called","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/net/impl/tcp/NetServerImpl.java","lineNumber":387,"sourceCode":"      long checkIntervalForStatsInMillis = options.getCheckIntervalForStatsTimeUnit().toMillis(options.getCheckIntervalForStats());\n      trafficShapingHandler.configure(options.getOutboundGlobalBandwidth(), options.getInboundGlobalBandwidth(), checkIntervalForStatsInMillis);\n      if (options.getPeakOutboundGlobalBandwidth() != 0) {\n        trafficShapingHandler.setMaxGlobalWriteSize(options.getPeakOutboundGlobalBandwidth());\n      }\n      if (options.getMaxDelayToWait() != 0) {\n        long maxDelayToWaitInMillis = options.getMaxDelayToWaitTimeUnit().toMillis(options.getMaxDelayToWait());\n        trafficShapingHandler.setMaxWriteDelay(maxDelayToWaitInMillis);\n      }\n      promise.complete(true);\n    } else {\n      log.info(\"Not updating traffic shaping options as they have not changed\");\n      promise.complete(false);\n    }\n  }\n\n  private synchronized Future<Channel> bind(ContextInternal context, SocketAddress localAddress) {\n    if (listening) {\n      throw new IllegalStateException(\"Listen already called\");\n    }\n\n    this.listening = true;\n    this.eventLoop = context.nettyEventLoop();\n\n    SocketAddress bindAddress;\n    Map<ServerID, NetServerInternal> sharedNetServers = vertx.sharedTcpServers();\n    synchronized (sharedNetServers) {\n      actualPort = localAddress.port();\n      String hostOrPath = localAddress.isInetSocket() ? localAddress.host() : localAddress.path();\n      NetServerImpl main;\n      boolean shared;\n      ServerID id;\n      if (actualPort > 0 || localAddress.isDomainSocket()) {\n        id = new ServerID(actualPort, hostOrPath);\n        main = (NetServerImpl) sharedNetServers.get(id);\n        shared = true;\n        bindAddress = localAddress;","sourceCodeStart":369,"sourceCodeEnd":405,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/net/impl/tcp/NetServerImpl.java#L369-L405","documentation":"Each NetServer instance can bind exactly once. The internal 'listening' flag is set in bind(), and any subsequent bind attempt on the same instance throws IllegalStateException. To listen again you must create a new server instance.","triggerScenarios":"Calling listen() twice on the same NetServer; retrying listen after a failure without recreating the server; code paths that can invoke listen more than once (e.g. restart logic).","commonSituations":"Application restart/redeploy logic reusing the server object; retry wrappers around listen(); tests that call listen in setup and per test method on a shared instance.","solutions":["Call listen() only once per NetServer; create a new instance via vertx.createNetServer() for re-listen or retry","Close the existing server (server.close()) and create a fresh instance before listening again","Move listen() out of retry loops and retry only the surrounding business logic"],"exampleFix":"// before\nserver.listen(1234);\nserver.listen(1234); // IllegalStateException: Listen already called\n// after\nserver.listen(1234);\nNetServer second = vertx.createNetServer();\nsecond.connectHandler(server.connectHandler()); // or reconfigure\nsecond.listen(1234);","handlingStrategy":"validation","validationCode":"AtomicBoolean started = new AtomicBoolean();\nif (started.compareAndSet(false, true)) {\n  server.listen(port);\n}","typeGuard":null,"tryCatchPattern":"try {\n  server.listen(port);\n} catch (IllegalStateException e) {\n  if (!e.getMessage().contains(\"Listen already called\")) throw e;\n  // ignore: already listening\n}","preventionTips":["Treat NetServer as single-use: one listen per instance","For retries/restarts, close then create a fresh server via vertx.createNetServer()","Guard listen() behind an idempotent start() method"],"tags":["vertx","net-server","illegal-state","double-listen"],"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"}