eclipse-vertx/vert.x · error · VertxException

ALPN is not available for OpenSSL SSL/TLS engine

Error message

ALPN is not available for OpenSSL SSL/TLS engine

What it means

resolveEngineOptions throws VertxException when ALPN is requested with the OpenSSL engine but the loaded netty-tcnative/OpenSSL build does not support ALPN. Vert.x cannot negotiate protocols like HTTP/2 over that engine.

Source

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

      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();
      }
    }
    return size;
  }

  Future<P> resolveSslContextProvider(SSLOptions options,

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Add the io.netty:netty-tcnative-boringssl-static dependency (includes ALPN support).
2. Ensure the matching native library is on java.library.path if using the non-static variant.
3. Upgrade netty-tcnative to a current version.
4. Fall back to the JDK engine with ALPN support (JDK 9+), or disable ALPN.

Example fix

// before
<!-- no tcnative -->
options.setSslEngineOptions(new OpenSSLEngineOptions()).setUseAlpn(true);
// after
<dependency><groupId>io.netty</groupId><artifactId>netty-tcnative-boringssl-static</artifactId></dependency>

if (useAlpn && engine instanceof OpenSSLEngineOptions && !OpenSSLEngineOptions.isAlpnAvailable()) {
  throw new IllegalStateException("netty-tcnative with ALPN support required");
}

try { resolve(); } catch (VertxException e) { engine = new JdkSSLEngineOptions(); /* requires JDK9+ */ }

When it happens

Trigger: setUseAlpn(true) with OpenSSLEngineOptions while OpenSSLEngineOptions.isAlpnAvailable() returns false — typically a missing or old netty-tcnative native library.

Common situations: Missing native tcnative .so/.dll on the host; using netty-tcnative statically linked variant older than ALPN support; wrong architecture native library.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

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

Related errors

• ALPN not available for JDK SSL/TLS engine
• SSL configuration is necessary for a QUIC server
• Not 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/2ce7a806dd9c3732. Report an issue: GitHub.