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

Supply an explicit SslSocketFactory via okHttpChannelBuilder.sslSocketFactory(...) so gRPC does not need the default SSLContext

grpc/grpc-java · critical · RuntimeException

TLS Provider failure

Error message

TLS Provider failure

What it means

OkHttpChannelBuilder.createSslSocketFactory wraps GeneralSecurityException from SSLContext.getInstance("Default") / getSocketFactory() in a RuntimeException. It means the default TLS provider cannot supply an SSL socket factory, typically because the platform provider is broken or missing TLS support.

Source

Thrown at okhttp/src/main/java/io/grpc/okhttp/OkHttpChannelBuilder.java:609

  }

  void setStatsEnabled(boolean value) {
    this.managedChannelImplBuilder.setStatsEnabled(value);
  }

  @VisibleForTesting
  @Nullable
  SSLSocketFactory createSslSocketFactory() {
    switch (negotiationType) {
      case TLS:
        try {
          if (sslSocketFactory == null) {
            SSLContext sslContext = SSLContext.getInstance("Default", Platform.get().getProvider());
            sslSocketFactory = sslContext.getSocketFactory();
          }
          return sslSocketFactory;
        } catch (GeneralSecurityException gse) {
          throw new RuntimeException("TLS Provider failure", gse);
        }
      case PLAINTEXT:
        return null;
      default:
        throw new RuntimeException("Unknown negotiation type: " + negotiationType);
    }
  }



  private static final EnumSet<TlsChannelCredentials.Feature> understoodTlsFeatures =
      EnumSet.of(
          TlsChannelCredentials.Feature.MTLS, TlsChannelCredentials.Feature.CUSTOM_MANAGERS);

  static SslSocketFactoryResult sslSocketFactoryFrom(ChannelCredentials creds) {
    if (creds instanceof TlsChannelCredentials) {
      TlsChannelCredentials tlsCreds = (TlsChannelCredentials) creds;
      Set<TlsChannelCredentials.Feature> incomprehensible =

View on GitHub (pinned to 64daddc1f3)

Solutions

Supply an explicit SslSocketFactory via okHttpChannelBuilder.sslSocketFactory(...) so gRPC does not need the default SSLContext
Check registered security providers (Security.getProviders()) and ensure a provider supporting SSLContext.TLS is present
Call Platform.get().getProvider() logic implicitly — verify the Conscrypt/Google Play provider is installed on constrained platforms
Use usePlaintext() if TLS is genuinely not needed

Example fix

// before
OkHttpChannel.forAddress(host, port).build(); // TLS default, provider failure
// after
SSLSocketFactory factory = (SSLSocketFactory) SSLSocketFactory.getDefault();
OkHttpChannel.forAddress(host, port).sslSocketFactory(factory).build();

Defensive patterns

Strategy: fallback

Validate before calling

try { SSLContext.getInstance("Default"); } catch (GeneralSecurityException e) { /* supply explicit sslSocketFactory */ }

Try / catch

try { builder.build(); } catch (RuntimeException e) { if (e.getMessage().contains("TLS Provider failure")) { builder.sslSocketFactory(defaultFactory()); return builder.build(); } throw e; }

Prevention

Always provide an explicit SSLSocketFactory in constrained runtimes
Verify security providers at app startup
Prefer plaintext only when explicitly safe

When it happens

Trigger: Building an OkHttpChannel with negotiationType TLS when sslSocketFactory was not supplied, and SSLContext.getInstance("Default", provider) throws GeneralSecurityException (provider unavailable, no TLS algorithm, misconfigured security provider).

Common situations: Custom JVMs without default TLS provider (early access/limited JDK builds), overridden security providers, Android devices lacking a proper TLS provider, registerProvider mistakes.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

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/f11d1b008b564d2f. Report an issue: GitHub.