What causes "TLS Provider failure" in grpc/grpc-java?

Inspect the wrapped GeneralSecurityException cause for the root problem (e.g. UnrecoverableKeyException, NoSuchAlgorithmException)

grpc/grpc-java · error · RuntimeException

TLS Provider failure

Error message

TLS Provider failure

What it means

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'.

Source

Thrown at okhttp/src/main/java/io/grpc/okhttp/OkHttpServerBuilder.java:451

      } // else don't have a client cert
      TrustManager[] tm = null;
      if (tlsCreds.getTrustManagers() != null) {
        tm = tlsCreds.getTrustManagers().toArray(new TrustManager[0]);
      } else if (tlsCreds.getRootCertificates() != null) {
        try {
          tm = createTrustManager(tlsCreds.getRootCertificates());
        } catch (GeneralSecurityException gse) {
          log.log(Level.FINE, "Exception loading root certificates from credential", gse);
          return HandshakerSocketFactoryResult.error(
              "Unable to load root certificates: " + gse.getMessage());
        }
      } // else use system default
      SSLContext sslContext;
      try {
        sslContext = SSLContext.getInstance("TLS", Platform.get().getProvider());
        sslContext.init(km, tm, null);
      } catch (GeneralSecurityException gse) {
        throw new RuntimeException("TLS Provider failure", gse);
      }
      SSLSocketFactory sslSocketFactory = sslContext.getSocketFactory();
      switch (tlsCreds.getClientAuth()) {
        case OPTIONAL:
          sslSocketFactory = new ClientCertRequestingSocketFactory(sslSocketFactory, false);
          break;

        case REQUIRE:
          sslSocketFactory = new ClientCertRequestingSocketFactory(sslSocketFactory, true);
          break;

        case NONE:
          // NOOP; this is the SSLContext default
          break;

        default:
          return HandshakerSocketFactoryResult.error(
              "Unknown TlsServerCredentials.ClientAuth value: " + tlsCreds.getClientAuth());

View on GitHub (pinned to 64daddc1f3)

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

Example fix

// before
KeyManagerFactory kmf = KeyManagerFactory.getInstance("SunX509"); // wrong algorithm on some providers
// after
KeyManagerFactory kmf = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());

Defensive patterns

Strategy: try-catch

Validate before calling

try {
  SSLContext ctx = SSLContext.getInstance("TLS");
  ctx.init(keyManagers, trustManagers, null);
} catch (GeneralSecurityException e) {
  throw new IllegalStateException("Invalid TLS material: " + e.getMessage(), e);
}

Try / catch

try { server = OkHttpServerBuilder.forPort(port, tlsCreds).build().start(); }
catch (RuntimeException e) {
  if (e.getMessage().contains("TLS Provider failure")) { /* inspect e.getCause() (GeneralSecurityException) and fix keys/providers */ throw e; }
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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).

Understand the failure class

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

Related errors

AI-assisted analysis of grpc/grpc-java@64daddc1f3 (2026-09-08). Data as JSON: /api/errors/2cfde324d47fbc1f. Report an issue: GitHub.