grpc/grpc-java · error · IllegalStateException

Could not find TLS ALPN provider; no working netty-tcnative,

Error message

Could not find TLS ALPN provider; no working netty-tcnative, Conscrypt, or Jetty NPN/ALPN available

What it means

defaultSslProvider() auto-detects a TLS ALPN-capable provider by probing netty-tcnative (OpenSSL), Conscrypt, and Jetty ALPN in order. If all three are unavailable it throws IllegalStateException, since gRPC requires one of them for HTTP/2 over TLS.

Source

Thrown at netty/src/main/java/io/grpc/netty/GrpcSslContexts.java:257

   */
  private static SslProvider defaultSslProvider() {
    if (OpenSsl.isAvailable()) {
      logger.log(Level.FINE, "Selecting OPENSSL");
      return SslProvider.OPENSSL;
    }
    Provider provider = findJdkProvider();
    if (provider != null) {
      logger.log(Level.FINE, "Selecting JDK with provider {0}", provider);
      return SslProvider.JDK;
    }
    logger.log(Level.INFO, "Java 9 ALPN API unavailable (this may be normal)");
    logger.log(Level.INFO, "netty-tcnative unavailable (this may be normal)",
        OpenSsl.unavailabilityCause());
    logger.log(Level.INFO, "Conscrypt not found (this may be normal)",
        ConscryptHolder.UNAVAILABILITY_CAUSE);
    logger.log(Level.INFO, "Jetty ALPN unavailable (this may be normal)",
        JettyTlsUtil.getJettyAlpnUnavailabilityCause());
    throw new IllegalStateException(
        "Could not find TLS ALPN provider; "
        + "no working netty-tcnative, Conscrypt, or Jetty NPN/ALPN available");
  }

  private static Provider findJdkProvider() {
    for (Provider provider : Security.getProviders("SSLContext.TLS")) {
      if (SUN_PROVIDER_NAME.equals(provider.getName())) {
        if (JettyTlsUtil.isJettyAlpnConfigured()
            || JettyTlsUtil.isJettyNpnConfigured()
            || JettyTlsUtil.isJava9AlpnAvailable()) {
          return provider;
        }
      } else if (IBM_PROVIDER_NAME.equals(provider.getName())
          || OPENJSSE_PROVIDER_NAME.equals(provider.getName())
          || BCJSSE_PROVIDER_NAME.equals(provider.getName())) {
        if (JettyTlsUtil.isJava9AlpnAvailable()) {
          return provider;
        }

View on GitHub (pinned to 64daddc1f3)

Solutions

Add io.grpc:grpc-netty-shaded's companion netty-tcnative-boringssl-static to dependencies
Add org.conscrypt:conscrypt-openjdk-ribbon and register the provider
On Java 8, install the Jetty ALPN boot agent
Upgrade to Java 9+ and rely on JDK ALPN support

Example fix

// before: no TLS provider on classpath
// after
implementation 'io.netty:netty-tcnative-boringssl-static:2.0.61.Final'
// or
implementation 'org.conscrypt:conscrypt-openjdk-ribbon:2.5.2'

Defensive patterns

Strategy: validation

Validate before calling

boolean tlsReady = OpenSsl.isAvailable() || ConscryptHolder.UNAVAILABILITY_CAUSE == null || JettyTlsUtil.isJettyAlpnAvailable() || JettyTlsUtil.isJava9AlpnAvailable(); if (!tlsReady) throw new IllegalStateException("No TLS ALPN provider on classpath");

Type guard

boolean hasTlsProvider() { return OpenSsl.isAvailable() || isConscryptRegistered() || JettyTlsUtil.isJettyAlpnAvailable(); }

Try / catch

try { return GrpcSslContexts.configure(builder); } catch (IllegalStateException e) { log.severe("Add netty-tcnative-boringssl-static or conscrypt to dependencies"); throw e; }

Prevention

Add netty-tcnative-boringssl-static or conscrypt-openjdk to every service deploying TLS
Verify native libraries survive shading/fat-jar packaging
Smoke-test TLS channel creation at app startup

When it happens

Trigger: Calling GrpcSslContexts.configure(builder) (default provider resolution) or building a Netty channel/server with TlsChannelCredentials/TlsServerCredentials on a JVM with none of the three providers present.

Common situations: Java 8 without Jetty ALPN agent and no Conscrypt/tcnative on the classpath; slim Docker images stripped of native libs; fat-jar packaging excluding native tcnative binaries; forgetting the conscrypt dependency.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 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/491e4bd4cd9e767c. Report an issue: GitHub.