grpc/grpc-java · error · IllegalArgumentException

Could not find Jetty NPN/ALPN or Conscrypt as installed JDK

Error message

Could not find Jetty NPN/ALPN or Conscrypt as installed JDK providers

What it means

GrpcSslContexts.configure() with SslProvider.JDK requires a JDK-level TLS provider that supports ALPN (Jetty NPN/ALPN, Conscrypt, or Java 9+ providers). If findJdkProvider() finds none, this IllegalArgumentException is thrown because gRPC over HTTP/2 cannot negotiate protocols.

Source

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

   */
  @CanIgnoreReturnValue
  public static SslContextBuilder configure(SslContextBuilder builder) {
    return configure(builder, defaultSslProvider());
  }

  /**
   * Set ciphers and APN appropriate for gRPC. Precisely what is set is permitted to change, so if
   * an application requires particular settings it should override the options set here. For
   * client builders, HTTPS endpoint identification is enabled by default.
   */
  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1784")
  @CanIgnoreReturnValue
  public static SslContextBuilder configure(SslContextBuilder builder, SslProvider provider) {
    switch (provider) {
      case JDK: {
        Provider jdkProvider = findJdkProvider();
        if (jdkProvider == null) {
          throw new IllegalArgumentException(
              "Could not find Jetty NPN/ALPN or Conscrypt as installed JDK providers");
        }
        return configure(builder, jdkProvider);
      }
      case OPENSSL: {
        ApplicationProtocolConfig apc;
        if (OpenSsl.isAlpnSupported()) {
          apc = NPN_AND_ALPN;
        } else {
          apc = NPN;
        }
        return builder
            .sslProvider(SslProvider.OPENSSL)
            .ciphers(Http2SecurityUtil.CIPHERS, SupportedCipherSuiteFilter.INSTANCE)
            .applicationProtocolConfig(apc)
            .endpointIdentificationAlgorithm(DEFAULT_ENDPOINT_IDENTIFICATION_ALGORITHM);
      }
      default:

View on GitHub (pinned to 64daddc1f3)

Solutions

Add Conscrypt to the classpath and register it as a security provider
On Java 8, install the Jetty ALPN boot jar/agent matching the JDK version
Use SslProvider.OPENSSL with netty-tcnative instead of JDK
Run on Java 9+ where ALPN is built in

Example fix

// before
GrpcSslContexts.configure(SslContextBuilder.forClient(), SslProvider.JDK);
// after
Security.insertProviderAt(new OpenSSLProvider(), 1); // or add conscrypt-openjdk to deps
GrpcSslContexts.configure(SslContextBuilder.forClient(), SslProvider.OPENSSL);

Defensive patterns

Strategy: validation

Validate before calling

if (JettyTlsUtil.getJettyAlpnUnavailabilityCause() != null && ConscryptHolder.UNAVAILABILITY_CAUSE != null && OpenSsl.isAvailable() == false) { /* no ALPN-capable provider */ }

Type guard

boolean hasAlpnProvider() { return GrpcSslContexts.class != null && (JettyTlsUtil.isJava9AlphAvailable() || isConscryptPresent() || OpenSsl.isAvailable()); }

Try / catch

try { GrpcSslContexts.configure(b, SslProvider.JDK); } catch (IllegalArgumentException e) { return GrpcSslContexts.configure(b, SslProvider.OPENSSL); }

Prevention

Pin Conscrypt or netty-tcnative in production dependencies
Verify ALPN availability at startup with a smoke test
On Java 8 always install the matching Jetty ALPN boot jar

When it happens

Trigger: Calling GrpcSslContexts.configure(SslContextBuilder, SslProvider.JDK) (directly or via defaultSslProvider resolution) on a JVM with no ALPN-capable SSL provider registered.

Common situations: Running on Java 8 without the Jetty ALPN boot classpath agent or Conscrypt; using a JDK whose SSLContext.TLS providers lack ALPN support; explicitly forcing SslProvider.JDK when only OpenSSL would work.

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.

Related errors

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