grpc/grpc-java · error · UnsupportedOperationException

Unsupported configurations in UpstreamTlsContext!

Error message

Unsupported configurations in UpstreamTlsContext!

What it means

CertProviderClientSslContextProviderFactory.getProvider converts an xDS UpstreamTlsContext into a client SSL context provider backed by certificate providers. Only supported CommonTlsContext shapes are handled; when the upstream TLS configuration does not match any supported case, the factory throws UnsupportedOperationException with this message.

Source

Thrown at xds/src/main/java/io/grpc/xds/internal/security/certprovider/CertProviderClientSslContextProviderFactory.java:79

    CommonTlsContext commonTlsContext = upstreamTlsContext.getCommonTlsContext();
    CertificateValidationContext staticCertValidationContext
        = CertProviderSslContextProvider.getStaticValidationContext(commonTlsContext);
    CommonTlsContext.CertificateProviderInstance rootCertInstance
        = CertProviderSslContextProvider.getRootCertProviderInstance(commonTlsContext);
    CommonTlsContext.CertificateProviderInstance certInstance
        = CertProviderSslContextProvider.getCertProviderInstance(commonTlsContext);
    if (CommonTlsContextUtil.hasCertProviderInstance(upstreamTlsContext.getCommonTlsContext())
        || CommonTlsContextUtil.isUsingSystemRootCerts(upstreamTlsContext.getCommonTlsContext())) {
      return new CertProviderClientSslContextProvider(
          node,
          certProviders,
          certInstance,
          rootCertInstance,
          staticCertValidationContext,
          upstreamTlsContext,
          certificateProviderStore);
    }
    throw new UnsupportedOperationException("Unsupported configurations in UpstreamTlsContext!");
  }
}

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Use certificate provider instances (tls_certificate_provider_instance / ca_certificate_provider_instance) in the UpstreamTlsContext's CommonTlsContext, with matching entries in the bootstrap certProviders
2. Upgrade grpc-java to a version supporting the desired UpstreamTlsContext configuration form
3. Configure TLS out-of-band (custom ManagedChannel credentials) if xDS cannot express this TLS config
4. Pre-validate UpstreamTlsContext protos in the control plane against grpc-java's supported set

Example fix

// before: static inline certs in upstream tls context
commonTlsContext.tlsCertificates = [{certificate_chain: inline_bytes:..., private_key: inline_bytes:...}]
// after: cert provider instance
commonTlsContext.tlsCertificateCertificateProviderInstance = {plugin_name: "file_watcher", instance_name: "client_cert"}

boolean supported(UpstreamTlsContext ctx) {
  CommonTlsContext c = ctx.getCommonTlsContext();
  return c.getTlsCertificateCertificateProviderInstanceCase()
      == CommonTlsContext.TlsCertificateCertificateProviderInstanceCase.CERTIFICATE_PROVIDER_INSTANCE;
}
if (!supported(upstreamTlsContext)) throw new IllegalArgumentException("unsupported UpstreamTlsContext");

try {
  provider = certProviderClientSslContextProviderFactory.getProvider(...);
} catch (UnsupportedOperationException e) {
  logger.error("xDS client TLS config unsupported; use cert-provider instances", e);
  throw new ConfigException(e);
}

When it happens

Trigger: Client channel configured with an UpstreamTlsContext whose CommonTlsContext uses material sources or validation contexts unsupported by the cert-provider path (e.g. inline/static PEM instead of certificate provider instances); getProvider exhausts its supported branches and throws.

Common situations: Migrating Envoy-style upstream TLS configs to grpc-java xDS; mesh control planes emitting tls_context material that grpc-java does not implement; missing cert provider plugin config in the bootstrap file.

Related errors

• Unsupported configurations in DownstreamTlsContext!
• 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/e53af28364d8a379. Report an issue: GitHub.