{"record":{"id":"3b1ce9cf6b22afea","repo":"grpc/grpc-java","slug":"common-tls-context-with-tls-params-is-not-supporte","errorCode":null,"errorMessage":"common-tls-context with tls_params is not supported","messagePattern":"common-tls-context with tls_params is not supported","errorType":"validation","errorClass":"ResourceInvalidException","httpStatus":null,"severity":"error","filePath":"xds/src/main/java/io/grpc/xds/XdsClusterResource.java","lineNumber":456,"sourceCode":"    if (upstreamTlsContext.hasCommonTlsContext()) {\n      validateCommonTlsContext(upstreamTlsContext.getCommonTlsContext(), certProviderInstances,\n          false);\n    } else {\n      throw new ResourceInvalidException(\"common-tls-context is required in upstream-tls-context\");\n    }\n    return upstreamTlsContext;\n  }\n\n  @VisibleForTesting\n  static void validateCommonTlsContext(\n      CommonTlsContext commonTlsContext, Set<String> certProviderInstances, boolean server)\n      throws ResourceInvalidException {\n    if (commonTlsContext.hasCustomHandshaker()) {\n      throw new ResourceInvalidException(\n          \"common-tls-context with custom_handshaker is not supported\");\n    }\n    if (commonTlsContext.hasTlsParams()) {\n      throw new ResourceInvalidException(\"common-tls-context with tls_params is not supported\");\n    }\n    if (commonTlsContext.hasValidationContextSdsSecretConfig()) {\n      throw new ResourceInvalidException(\n          \"common-tls-context with validation_context_sds_secret_config is not supported\");\n    }\n    String certInstanceName = getIdentityCertInstanceName(commonTlsContext);\n    if (certInstanceName == null) {\n      if (server) {\n        throw new ResourceInvalidException(\n            \"tls_certificate_provider_instance is required in downstream-tls-context\");\n      }\n      if (commonTlsContext.getTlsCertificatesCount() > 0) {\n        throw new ResourceInvalidException(\n            \"tls_certificate_provider_instance is unset\");\n      }\n      if (commonTlsContext.getTlsCertificateSdsSecretConfigsCount() > 0) {\n        throw new ResourceInvalidException(\n            \"tls_certificate_provider_instance is unset\");","sourceCodeStart":438,"sourceCodeEnd":474,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/XdsClusterResource.java#L438-L474","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the tls_params block from common_tls_context; gRPC ignores it and manages TLS versions itself.","Configure TLS version/ciphers on the client via TlsChannelCredentials or on the server via TlsServerCredentials instead of xDS.","If the control plane cannot be changed, filter out tls_params before serving the resource to gRPC clients."],"exampleFix":"// before\n\"common_tls_context\": {\n  \"tls_params\": { \"tls_minimum_protocol_version\": \"TLSv1_2\" },\n  \"validation_context\": { ... }\n}\n// after\n\"common_tls_context\": { \"validation_context\": { ... } }","handlingStrategy":"validation","validationCode":"if (commonTlsContext.hasTlsParams()) {\n  throw new IllegalArgumentException(\"tls_params unsupported by grpc-xds; set TLS params client-side\");\n}","typeGuard":null,"tryCatchPattern":"try { /* consume resource */ } catch (ResourceInvalidException e) {\n  if (e.getMessage().contains(\"tls_params\")) { fixControlPlaneResource(); }\n}","preventionTips":["Configure TLS versions/ciphers via TlsChannelCredentials/TlsServerCredentials, never xDS tls_params.","Add a lint rule in your control plane rejecting tls_params for gRPC consumer configs."],"tags":["grpc","xds","tls","tls-params"],"backgroundTag":"unsupported-config-value","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}