eclipse-vertx/vert.x · error · IllegalStateException

Not listening

Error message

Not listening

What it means

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.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/tcp/TcpHttpServer.java:87

                       SSLEngineOptions engineOptions, HttpServerMetrics<?, ?> httpMetrics, boolean registerWebSocketWriteHandlers) {
    this.vertx = vertx;
    this.config = config;
    this.ssl = sslOptions != null;
    this.sslOptions = sslOptions;
    this.engineOptions = engineOptions;
    this.registerWebSocketWriteHandlers = registerWebSocketWriteHandlers;
    this.httpMetrics = httpMetrics;
    this.manageMetrics = httpMetrics == null;
  }

  @Override
  public Future<Boolean> updateSSLOptions(ServerSSLOptions options, boolean force) {
    NetServer s;
    synchronized (this) {
      s = tcpServer;
    }
    if (s == null) {
      throw new IllegalStateException("Not listening");
    }
    options = options.copy();
    return s.updateSSLOptions(options, force);
  }

  @Override
  public Future<Boolean> updateTrafficShapingOptions(TrafficShapingOptions options) {
    NetServer s;
    synchronized (this) {
      s = tcpServer;
    }
    if (s == null) {
      throw new IllegalStateException("Not listening");
    }
    return s.updateTrafficShapingOptions(options);
  }

  @Override

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Call updateSSLOptions() only after the listen() future has succeeded
2. Check the listen() result/future before scheduling SSL option updates
3. Gate the update on the server's listening state (e.g., track it in your own lifecycle code)
4. If the server is stopped, set the SSL options before listen() instead of hot-updating

Example fix

// before
server.updateSSLOptions(newOpts, false); // throws: Not listening
server.listen(port);
// after
server.listen(port).onSuccess(v -> server.updateSSLOptions(newOpts, false));

if (server.actualPort() == 0) { throw new IllegalStateException("Cannot update SSL options: server not listening"); }
server.updateSSLOptions(newOpts, false);

try { server.updateSSLOptions(opts, false); } catch (IllegalStateException e) { log.error("updateSSLOptions requires a listening server", e); }

When it happens

Trigger: Calling updateSSLOptions(ServerSSLOptions, boolean) before listen() completes, after listen() failed, or after the server was shut down and the internal tcpServer reference cleared.

Common situations: 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.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Request has already been read
• Response has already been written
• Please set handler before server is listening
• PQC enforcement policy ${pqcPolicy} requires PQ compliant na
• PQC enforcement policy ${pqcPolicy} requires PQ compliant na

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/d30d6d7b30e6ff89. Report an issue: GitHub.