{"record":{"id":"66bbfcfb72d3fb7b","repo":"eclipse-vertx/vert.x","slug":"alpn-not-available-for-jdk-ssl-tls-engine","errorCode":null,"errorMessage":"ALPN not available for JDK SSL/TLS engine","messagePattern":"ALPN not available for JDK 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":139,"sourceCode":"      }\n    }\n    if (engineOptions == null) {\n      engineOptions = new JdkSSLEngineOptions();\n    } else if (engineOptions instanceof OpenSSLEngineOptions) {\n      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      }","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/internal/tls/SslContextManager.java#L121-L157","documentation":"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.","triggerScenarios":"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).","commonSituations":"Running on Java 8 without the Jetty ALPN boot jar/agent; forgetting the -javaagent alpn argument; JDK with constrained crypto providers.","solutions":["Upgrade to JDK 9+ (ideally 11/17/21) where ALPN is built in.","On JDK 8, install the Jetty ALPN boot jar or ALPN agent and add it via -javaagent.","Switch to OpenSSLEngineOptions (netty-tcnative) which provides ALPN without JDK support.","Disable ALPN/HTTP/2 if not needed (setUseAlpn(false))."],"exampleFix":"// before\njava -jar app.jar // JDK 8, no ALPN\n// after\njava -javaagent:jetty-alpn-agent.jar -jar app.jar","handlingStrategy":"validation","validationCode":"if (useAlpn && engine instanceof JdkSSLEngineOptions && !JdkSSLEngineOptions.isAlpnAvailable()) {\n  throw new IllegalStateException(\"JDK ALPN unavailable; upgrade JDK or attach alpn agent\");\n}","typeGuard":null,"tryCatchPattern":"try { resolve(); } catch (VertxException e) { engine = new OpenSSLEngineOptions(); /* fallback */ }","preventionTips":["Run JDK 9+ where ALPN is built in","On JDK 8 always launch with the Jetty ALPN agent","Check JdkSSLEngineOptions.isAlpnAvailable() at startup when enabling HTTP/2"],"tags":["ssl","alpn","http2","jdk"],"backgroundTag":"feature-not-enabled","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"}