eclipse-vertx/vert.x · error · VertxException

ALPN not available for JDK SSL/TLS engine

Error message

ALPN not available for JDK SSL/TLS engine

What it means

resolveEngineOptions throws VertxException when ALPN is requested (useAlpn) with the JDK SSL engine but the running JVM does not support ALPN (Jetty ALPN agent absent or JDK too old). Vert.x cannot negotiate HTTP/2 over TLS in that setup.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/internal/tls/SslContextManager.java:139

      }
    }
    if (engineOptions == null) {
      engineOptions = new JdkSSLEngineOptions();
    } else if (engineOptions instanceof OpenSSLEngineOptions) {
      if (!OpenSsl.isAvailable()) {
        VertxException ex = new VertxException("OpenSSL is not available");
        Throwable cause = OpenSsl.unavailabilityCause();
        if (cause != null) {
          ex.initCause(cause);
        }
        throw ex;
      }
    }

    if (useAlpn) {
      if (engineOptions instanceof JdkSSLEngineOptions) {
        if (!JdkSSLEngineOptions.isAlpnAvailable()) {
          throw new VertxException("ALPN not available for JDK SSL/TLS engine");
        }
      }
      if (engineOptions instanceof OpenSSLEngineOptions) {
        if (!OpenSSLEngineOptions.isAlpnAvailable()) {
          throw new VertxException("ALPN is not available for OpenSSL SSL/TLS engine");
        }
      }
    }
    return engineOptions;
  }

  public synchronized int sniEntrySize() {
    int size = 0;
    for (Future<P> fut : sslContextProviderMap.values()) {
      SslContextProvider result = fut.result();
      if (result != null) {
        size += result.sniEntrySize();
      }

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Upgrade to JDK 9+ (ideally 11/17/21) where ALPN is built in.
2. On JDK 8, install the Jetty ALPN boot jar or ALPN agent and add it via -javaagent.
3. Switch to OpenSSLEngineOptions (netty-tcnative) which provides ALPN without JDK support.
4. Disable ALPN/HTTP/2 if not needed (setUseAlpn(false)).

Example fix

// before
java -jar app.jar // JDK 8, no ALPN
// after
java -javaagent:jetty-alpn-agent.jar -jar app.jar

if (useAlpn && engine instanceof JdkSSLEngineOptions && !JdkSSLEngineOptions.isAlpnAvailable()) {
  throw new IllegalStateException("JDK ALPN unavailable; upgrade JDK or attach alpn agent");
}

try { resolve(); } catch (VertxException e) { engine = new OpenSSLEngineOptions(); /* fallback */ }

When it happens

Trigger: HTTP/2 or TCP options with setUseAlpn(true) and JdkSSLEngineOptions selected while JdkSSLEngineOptions.isAlpnAvailable() is false (JDK < 9, or missing alpn-boot/ALPN agent on JDK 8).

Common situations: Running on Java 8 without the Jetty ALPN boot jar/agent; forgetting the -javaagent alpn argument; JDK with constrained crypto providers.

Understand the failure class

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

Related errors

• ALPN is not available for OpenSSL SSL/TLS engine
• http2MaxPoolSize must be > 0
• Cannot write frame with HTTP/1.x
• SSL configuration is necessary for a QUIC server
• A push response cannot promise another push

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