{"record":{"id":"2ce7a806dd9c3732","repo":"eclipse-vertx/vert.x","slug":"alpn-is-not-available-for-openssl-ssl-tls-engine","errorCode":null,"errorMessage":"ALPN is not available for OpenSSL SSL/TLS engine","messagePattern":"ALPN is not available for OpenSSL SSL/TLS engine","errorType":"exception","errorClass":"VertxException","httpStatus":null,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/internal/tls/SslContextManager.java","lineNumber":144,"sourceCode":"      if (!OpenSsl.isAvailable()) {\n        VertxException ex = new VertxException(\"OpenSSL is not available\");\n        Throwable cause = OpenSsl.unavailabilityCause();\n        if (cause != null) {\n          ex.initCause(cause);\n        }\n        throw ex;\n      }\n    }\n\n    if (useAlpn) {\n      if (engineOptions instanceof JdkSSLEngineOptions) {\n        if (!JdkSSLEngineOptions.isAlpnAvailable()) {\n          throw new VertxException(\"ALPN not available for JDK SSL/TLS engine\");\n        }\n      }\n      if (engineOptions instanceof OpenSSLEngineOptions) {\n        if (!OpenSSLEngineOptions.isAlpnAvailable()) {\n          throw new VertxException(\"ALPN is not available for OpenSSL SSL/TLS engine\");\n        }\n      }\n    }\n    return engineOptions;\n  }\n\n  public synchronized int sniEntrySize() {\n    int size = 0;\n    for (Future<P> fut : sslContextProviderMap.values()) {\n      SslContextProvider result = fut.result();\n      if (result != null) {\n        size += result.sniEntrySize();\n      }\n    }\n    return size;\n  }\n\n  Future<P> resolveSslContextProvider(SSLOptions options,","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/internal/tls/SslContextManager.java#L126-L162","documentation":"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.","triggerScenarios":"setUseAlpn(true) with OpenSSLEngineOptions while OpenSSLEngineOptions.isAlpnAvailable() returns false — typically a missing or old netty-tcnative native library.","commonSituations":"Missing native tcnative .so/.dll on the host; using netty-tcnative statically linked variant older than ALPN support; wrong architecture native library.","solutions":["Add the io.netty:netty-tcnative-boringssl-static dependency (includes ALPN support).","Ensure the matching native library is on java.library.path if using the non-static variant.","Upgrade netty-tcnative to a current version.","Fall back to the JDK engine with ALPN support (JDK 9+), or disable ALPN."],"exampleFix":"// before\n<!-- no tcnative -->\noptions.setSslEngineOptions(new OpenSSLEngineOptions()).setUseAlpn(true);\n// after\n<dependency><groupId>io.netty</groupId><artifactId>netty-tcnative-boringssl-static</artifactId></dependency>","handlingStrategy":"validation","validationCode":"if (useAlpn && engine instanceof OpenSSLEngineOptions && !OpenSSLEngineOptions.isAlpnAvailable()) {\n  throw new IllegalStateException(\"netty-tcnative with ALPN support required\");\n}","typeGuard":null,"tryCatchPattern":"try { resolve(); } catch (VertxException e) { engine = new JdkSSLEngineOptions(); /* requires JDK9+ */ }","preventionTips":["Include io.netty:netty-tcnative-boringssl-static in the build","Verify the native library loads on the target OS/arch in CI","Check OpenSSLEngineOptions.isAlpnAvailable() before selecting OpenSSL engine with ALPN"],"tags":["ssl","alpn","openssl","native"],"backgroundTag":"missing-dependency","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"}