{"record":{"id":"2cfde324d47fbc1f","repo":"grpc/grpc-java","slug":"tls-provider-failure-2cfde3","errorCode":null,"errorMessage":"TLS Provider failure","messagePattern":"TLS Provider failure","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"okhttp/src/main/java/io/grpc/okhttp/OkHttpServerBuilder.java","lineNumber":451,"sourceCode":"      } // else don't have a client cert\n      TrustManager[] tm = null;\n      if (tlsCreds.getTrustManagers() != null) {\n        tm = tlsCreds.getTrustManagers().toArray(new TrustManager[0]);\n      } else if (tlsCreds.getRootCertificates() != null) {\n        try {\n          tm = createTrustManager(tlsCreds.getRootCertificates());\n        } catch (GeneralSecurityException gse) {\n          log.log(Level.FINE, \"Exception loading root certificates from credential\", gse);\n          return HandshakerSocketFactoryResult.error(\n              \"Unable to load root certificates: \" + gse.getMessage());\n        }\n      } // else use system default\n      SSLContext sslContext;\n      try {\n        sslContext = SSLContext.getInstance(\"TLS\", Platform.get().getProvider());\n        sslContext.init(km, tm, null);\n      } catch (GeneralSecurityException gse) {\n        throw new RuntimeException(\"TLS Provider failure\", gse);\n      }\n      SSLSocketFactory sslSocketFactory = sslContext.getSocketFactory();\n      switch (tlsCreds.getClientAuth()) {\n        case OPTIONAL:\n          sslSocketFactory = new ClientCertRequestingSocketFactory(sslSocketFactory, false);\n          break;\n\n        case REQUIRE:\n          sslSocketFactory = new ClientCertRequestingSocketFactory(sslSocketFactory, true);\n          break;\n\n        case NONE:\n          // NOOP; this is the SSLContext default\n          break;\n\n        default:\n          return HandshakerSocketFactoryResult.error(\n              \"Unknown TlsServerCredentials.ClientAuth value: \" + tlsCreds.getClientAuth());","sourceCodeStart":433,"sourceCodeEnd":469,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/okhttp/src/main/java/io/grpc/okhttp/OkHttpServerBuilder.java#L433-L469","documentation":"When a TlsServerCredentials is configured with custom key/cert managers, handshakerSocketFactoryFrom builds an SSLContext using the provider returned by okhttp's Platform.get().getProvider() and initializes it. If the JVM's TLS provider fails (GeneralSecurityException: bad keys, unsupported algorithms, provider problems), it is rethrown as a RuntimeException named 'TLS Provider failure'.","triggerScenarios":"Building an OkHttp server with TlsServerCredentials configured via keyManager()/trustManager() where SSLContext.getInstance(\"TLS\", provider) or sslContext.init(...) throws GeneralSecurityException — e.g. invalid KeyManager/TrustManager, corrupted keystores, or unsupported algorithm names.","commonSituations":"Passing keystores loaded with the wrong password or format (PKCS12 vs JKS), key algorithms not supported by the platform provider, restricted crypto environments (FIPS, missing JCE unlimited policy on old JVMs).","solutions":["Inspect the wrapped GeneralSecurityException cause for the root problem (e.g. UnrecoverableKeyException, NoSuchAlgorithmException)","Verify keystore files, formats and passwords used to build the KeyManager/TrustManager","Ensure the JVM's default TLS provider supports the required algorithms (test SSLContext.getDefault()), or update to a newer JDK","If only custom trust is needed, use TlsServerCredentials trustManager with a valid CA cert, or drop custom managers to use the system default"],"exampleFix":"// before\nKeyManagerFactory kmf = KeyManagerFactory.getInstance(\"SunX509\"); // wrong algorithm on some providers\n// after\nKeyManagerFactory kmf = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());","handlingStrategy":"try-catch","validationCode":"try {\n  SSLContext ctx = SSLContext.getInstance(\"TLS\");\n  ctx.init(keyManagers, trustManagers, null);\n} catch (GeneralSecurityException e) {\n  throw new IllegalStateException(\"Invalid TLS material: \" + e.getMessage(), e);\n}","typeGuard":null,"tryCatchPattern":"try { server = OkHttpServerBuilder.forPort(port, tlsCreds).build().start(); }\ncatch (RuntimeException e) {\n  if (e.getMessage().contains(\"TLS Provider failure\")) { /* inspect e.getCause() (GeneralSecurityException) and fix keys/providers */ throw e; }\n}","preventionTips":["Validate keystores (format, password, algorithm) before building KeyManager/TrustManager","Test SSLContext initialization at startup with fail-fast health checks","Use a JDK whose default security provider supports your key algorithms"],"tags":["grpc","java","tls","ssl","runtime-exception"],"backgroundTag":"tls-handshake-failure","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}