eclipse-vertx/vert.x · error · NullPointerException

SSL configuration is necessary for a QUIC server

Error message

SSL configuration is necessary for a QUIC server

What it means

HttpServerBuilderImpl.build() throws a NullPointerException when the configured versions include HTTP/3 (QUIC) but no SSL options were set. QUIC mandates TLS 1.3, so a QUIC server cannot be created without an SSL/key-certificate configuration.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/impl/HttpServerBuilderImpl.java:78

  }

  public HttpServerBuilderImpl registerWebSocketWriteHandlers(boolean registerWebSocketWriteHandlers) {
    this.registerWebSocketWriteHandlers = registerWebSocketWriteHandlers;
    return this;
  }

  @Override
  public HttpServerBuilderImpl withConnectHandler(Handler<HttpConnection> handler) {
    this.connectHandler = handler;
    return this;
  }

  @Override
  public HttpServer build() {
    boolean useTcp = config.getVersions().contains(HttpVersion.HTTP_1_1) || config.getVersions().contains(HttpVersion.HTTP_2) || config.getVersions().contains(HttpVersion.HTTP_1_0);
    boolean useQuic = config.getVersions().contains(HttpVersion.HTTP_3);
    if (useQuic && sslOptions == null) {
      throw new NullPointerException("SSL configuration is necessary for a QUIC server");
    }
    HttpServer server;
    if (useTcp) {
      if (useQuic) {
        HybridHttpServer compositeServer = new HybridHttpServer(vertx, new HttpServerConfig(config), sslOptions.copy(), sslEngineOptions);
        server = new CleanableHttpServer(vertx, compositeServer);
      } else {
        if (sslOptions != null) {
          sslOptions = sslOptions.copy();
        }
        server = new CleanableHttpServer(vertx, new TcpHttpServer(vertx, new HttpServerConfig(config), sslOptions, sslEngineOptions, null, registerWebSocketWriteHandlers));
      }
    } else if (useQuic) {
      server = new CleanableHttpServer(vertx, new QuicHttpServer(vertx, new HttpServerConfig(config), sslOptions.copy(), null));
    } else {
      throw new IllegalArgumentException("You must set at least one supported HTTP version");
    }
    Handler<HttpConnection> handler = connectHandler;

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Call setSslOptions(new SslOptions().setKeyCertOptions(...).setTrustOptions(...)) with a valid key/certificate before build()
2. Remove HTTP_3 from the configured versions if QUIC is not actually needed
3. Ensure the TLS key/cert configuration is loaded from config/environment and passed to the builder

Example fix

// before
HttpServer server =.vertx.createHttpServer()
  .addVersion(HttpVersion.HTTP_3, 8443)
  .build(); // throws
// after
HttpServer server = vertx.createHttpServer()
  .addVersion(HttpVersion.HTTP_3, 8443)
  .setSslOptions(new SslOptions().setKeyCertOptions(new JksOptions().setPath("keystore.jks").setPassword("secret")))
  .build();

if (versions.contains(HttpVersion.HTTP_3) && sslOptions == null) {
  throw new IllegalArgumentException("HTTP/3 requires setSslOptions(...)");
}

boolean quicReady(HttpServerBuilder b) { return b.sslOptions() != null; } // or track sslOptions yourself before build()

try {
  server = builder.build();
} catch (NullPointerException e) {
  if ("SSL configuration is necessary for a QUIC server".equals(e.getMessage())) {
    // rebuild without HTTP_3 or with SSL options
  } else { throw e; }
}

When it happens

Trigger: Building an HttpServer with .addVersion(HttpVersion.HTTP_3, port) but never calling .setSslOptions(...) on the builder.

Common situations: Copy-pasting an HTTP/1.1/2 server config and adding HTTP/3 without key/cert setup; running in environments where key/cert paths are not provisioned (missing env/config).

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• You must set at least one supported HTTP version
• Timeout must be >= 0
• Only TLSv1.3 supported
• keepAliveTimeout must be >= 0
• http3MaxPoolSize must be > 0

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