grpc/grpc-java · error · UnsupportedOperationException

Unsupported configurations in DownstreamTlsContext!

Error message

Unsupported configurations in DownstreamTlsContext!

What it means

ServerSslContextProviderFactory.create builds an SSL context provider from an xDS DownstreamTlsContext for servers. It only supports configurations it recognizes (e.g. certificate-provider-based common TlsContext handled by certProviderServerSslContextProviderFactory); anything else falls through the checks and hits an explicit UnsupportedOperationException. This is the library saying the DownstreamTlsContext combination is not implemented.

Source

Thrown at xds/src/main/java/io/grpc/xds/internal/security/ServerSslContextProviderFactory.java:59

    this.certProviderServerSslContextProviderFactory = factory;
  }

  /** Creates a SslContextProvider from the given DownstreamTlsContext. */
  @Override
  public SslContextProvider create(
      DownstreamTlsContext downstreamTlsContext) {
    checkNotNull(downstreamTlsContext, "downstreamTlsContext");
    checkNotNull(
        downstreamTlsContext.getCommonTlsContext(),
        "downstreamTlsContext should have CommonTlsContext");
    if (CommonTlsContextUtil.hasCertProviderInstance(
        downstreamTlsContext.getCommonTlsContext())) {
      return certProviderServerSslContextProviderFactory.getProvider(
          downstreamTlsContext,
          bootstrapInfo.node().toEnvoyProtoNode(),
          bootstrapInfo.certProviders());
    }
    throw new UnsupportedOperationException("Unsupported configurations in DownstreamTlsContext!");
  }
}

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Switch the DownstreamTlsContext to a certificate-provider-based CommonTlsContext (e.g. use the same plugin names configured in gRPC bootstrap certProviders)
2. Check grpc-java version/release notes for which DownstreamTlsContext forms are supported and upgrade if a newer version adds support
3. Fall back to non-xDS TLS (in-process server TLS setup) if the required config form is unsupported
4. Validate the DownstreamTlsContext proto before deploying so unsupported shapes are caught at config time

Example fix

// before: file-based validation context unsupported by grpc-java xDS
downstreamTlsContext.commonTlsContext.validationContextType = trusted_ca(file:...)
// after: use certificate providers via bootstrap
downstreamTlsContext.commonTlsContext.tlsCertificateCertificateProviderInstance = {instance_name: "google_cloud_private_spiffe", certificate_name: "spiffe://..."}

// Check the DownstreamTlsContext shape before enabling xDS server security
boolean supported(DownstreamTlsContext ctx) {
  return ctx.hasCommonTlsContext()
      && (ctx.getCommonTlsContext().getTlsCertificateCertificateProviderInstanceCase()
             == CommonTlsContext.TlsCertificateCertificateProviderInstanceCase.CERTIFICATE_PROVIDER_INSTANCE);
}
if (!supported(downstreamTlsContext)) throw new IllegalArgumentException("unsupported DownstreamTlsContext");

try {
  provider = serverSslContextProviderFactory.create(...);
} catch (UnsupportedOperationException e) {
  logger.error("xDS server TLS config unsupported; check DownstreamTlsContext form", e);
  throw new ConfigException(e);
}

When it happens

Trigger: Configuring a server with securityTlsContext/DownstreamTlsContext whose CommonTlsContext uses validation contexts or TLS material forms not handled by the factory (e.g. static file-based certs, combined validation contexts) instead of a supported cert provider config; create() then throws.

Common situations: Users converting from file-based Envoy TLS configs to grpc-java xDS; control planes emitting tls_context fields grpc-java does not implement; older/newer xDS API surfaces with unsupported validation_context_type combinations.

Related errors

• Unsupported configurations in UpstreamTlsContext!
• Files were unmodified before their initial update. Probably
• common-tls-context is required in upstream-tls-context
• common-tls-context with custom_handshaker is not supported
• common-tls-context with tls_params is not supported

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