grpc/grpc-java · error · ResourceInvalidException

common-tls-context with tls_params is not supported

Error message

common-tls-context with tls_params is not supported

What it means

The xDS client does not honor tls_params in a common_tls_context; TLS parameters (min/max TLS version, cipher suites) are configured via gRPC's own ChannelCredentials, not via xDS. When tls_params is present the cluster resource is rejected with ResourceInvalidException.

Source

Thrown at xds/src/main/java/io/grpc/xds/XdsClusterResource.java:456

    if (upstreamTlsContext.hasCommonTlsContext()) {
      validateCommonTlsContext(upstreamTlsContext.getCommonTlsContext(), certProviderInstances,
          false);
    } else {
      throw new ResourceInvalidException("common-tls-context is required in upstream-tls-context");
    }
    return upstreamTlsContext;
  }

  @VisibleForTesting
  static void validateCommonTlsContext(
      CommonTlsContext commonTlsContext, Set<String> certProviderInstances, boolean server)
      throws ResourceInvalidException {
    if (commonTlsContext.hasCustomHandshaker()) {
      throw new ResourceInvalidException(
          "common-tls-context with custom_handshaker is not supported");
    }
    if (commonTlsContext.hasTlsParams()) {
      throw new ResourceInvalidException("common-tls-context with tls_params is not supported");
    }
    if (commonTlsContext.hasValidationContextSdsSecretConfig()) {
      throw new ResourceInvalidException(
          "common-tls-context with validation_context_sds_secret_config is not supported");
    }
    String certInstanceName = getIdentityCertInstanceName(commonTlsContext);
    if (certInstanceName == null) {
      if (server) {
        throw new ResourceInvalidException(
            "tls_certificate_provider_instance is required in downstream-tls-context");
      }
      if (commonTlsContext.getTlsCertificatesCount() > 0) {
        throw new ResourceInvalidException(
            "tls_certificate_provider_instance is unset");
      }
      if (commonTlsContext.getTlsCertificateSdsSecretConfigsCount() > 0) {
        throw new ResourceInvalidException(
            "tls_certificate_provider_instance is unset");

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Remove the tls_params block from common_tls_context; gRPC ignores it and manages TLS versions itself.
2. Configure TLS version/ciphers on the client via TlsChannelCredentials or on the server via TlsServerCredentials instead of xDS.
3. If the control plane cannot be changed, filter out tls_params before serving the resource to gRPC clients.

Example fix

// before
"common_tls_context": {
  "tls_params": { "tls_minimum_protocol_version": "TLSv1_2" },
  "validation_context": { ... }
}
// after
"common_tls_context": { "validation_context": { ... } }

if (commonTlsContext.hasTlsParams()) {
  throw new IllegalArgumentException("tls_params unsupported by grpc-xds; set TLS params client-side");
}

try { /* consume resource */ } catch (ResourceInvalidException e) {
  if (e.getMessage().contains("tls_params")) { fixControlPlaneResource(); }
}

When it happens

Trigger: A cluster's upstream_tls_context (or downstream_tls_context) contains common_tls_context.tls_params set (e.g. tls_minimum_protocol_version or cipher list). validateCommonTlsContext, invoked from validateUpstreamTlsContext, throws at XdsClusterResource.java:456.

Common situations: Control planes generated for Envoy that set TLS version/cipher tuning in tls_params; operators hardening TLS by editing the xDS resource instead of client-side options; gRPC mTLS examples adapted from Envoy docs.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• common-tls-context is required in upstream-tls-context
• common-tls-context with custom_handshaker is not supported
• common-tls-context with validation_context_sds_secret_config
• tls_certificate_provider_instance is required in downstream-
• tls_certificate_provider_instance is unset

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