{"record":{"id":"d30d6d7b30e6ff89","repo":"eclipse-vertx/vert.x","slug":"not-listening","errorCode":null,"errorMessage":"Not listening","messagePattern":"Not listening","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/http/impl/tcp/TcpHttpServer.java","lineNumber":87,"sourceCode":"                       SSLEngineOptions engineOptions, HttpServerMetrics<?, ?> httpMetrics, boolean registerWebSocketWriteHandlers) {\n    this.vertx = vertx;\n    this.config = config;\n    this.ssl = sslOptions != null;\n    this.sslOptions = sslOptions;\n    this.engineOptions = engineOptions;\n    this.registerWebSocketWriteHandlers = registerWebSocketWriteHandlers;\n    this.httpMetrics = httpMetrics;\n    this.manageMetrics = httpMetrics == null;\n  }\n\n  @Override\n  public Future<Boolean> updateSSLOptions(ServerSSLOptions options, boolean force) {\n    NetServer s;\n    synchronized (this) {\n      s = tcpServer;\n    }\n    if (s == null) {\n      throw new IllegalStateException(\"Not listening\");\n    }\n    options = options.copy();\n    return s.updateSSLOptions(options, force);\n  }\n\n  @Override\n  public Future<Boolean> updateTrafficShapingOptions(TrafficShapingOptions options) {\n    NetServer s;\n    synchronized (this) {\n      s = tcpServer;\n    }\n    if (s == null) {\n      throw new IllegalStateException(\"Not listening\");\n    }\n    return s.updateTrafficShapingOptions(options);\n  }\n\n  @Override","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/impl/tcp/TcpHttpServer.java#L69-L105","documentation":"TcpHttpServer.updateSSLOptions() throws IllegalStateException when the server is not listening (tcpServer == null). Hot-swapping SSL options (cert rotation, trust changes) operates on the underlying NetServer, which only exists after listen() has been called.","triggerScenarios":"Calling updateSSLOptions(ServerSSLOptions, boolean) before listen() completes, after listen() failed, or after the server was shut down and the internal tcpServer reference cleared.","commonSituations":"Certificate rotation job firing before server startup finished; updating SSL options on a stopped/redeployed server; race between a startup future and an admin endpoint triggering SSL updates.","solutions":["Call updateSSLOptions() only after the listen() future has succeeded","Check the listen() result/future before scheduling SSL option updates","Gate the update on the server's listening state (e.g., track it in your own lifecycle code)","If the server is stopped, set the SSL options before listen() instead of hot-updating"],"exampleFix":"// before\nserver.updateSSLOptions(newOpts, false); // throws: Not listening\nserver.listen(port);\n// after\nserver.listen(port).onSuccess(v -> server.updateSSLOptions(newOpts, false));","handlingStrategy":"validation","validationCode":"if (server.actualPort() == 0) { throw new IllegalStateException(\"Cannot update SSL options: server not listening\"); }\nserver.updateSSLOptions(newOpts, false);","typeGuard":null,"tryCatchPattern":"try { server.updateSSLOptions(opts, false); } catch (IllegalStateException e) { log.error(\"updateSSLOptions requires a listening server\", e); }","preventionTips":["Only hot-update SSL options from the listen() future's success callback","Set initial SSL options in configuration before listen()","Track server lifecycle state for any runtime update path"],"tags":["http","ssl","tls","lifecycle"],"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"}