{"record":{"id":"e765f92a4901bd4a","repo":"grpc/grpc-java","slug":"common-tls-context-is-required-in-downstream-tls-c","errorCode":null,"errorMessage":"common-tls-context is required in downstream-tls-context","messagePattern":"common-tls-context is required in downstream-tls-context","errorType":"exception","errorClass":"ResourceInvalidException","httpStatus":null,"severity":"error","filePath":"xds/src/main/java/io/grpc/xds/XdsListenerResource.java","lineNumber":302,"sourceCode":"    }\n\n    return FilterChain.create(\n        filterChainName,\n        filterChainMatch,\n        httpConnectionManager,\n        downstreamTlsContext,\n        tlsContextManager\n    );\n  }\n\n  @VisibleForTesting\n  static DownstreamTlsContext validateDownstreamTlsContext(\n      DownstreamTlsContext downstreamTlsContext, Set<String> certProviderInstances)\n      throws ResourceInvalidException {\n    if (downstreamTlsContext.hasCommonTlsContext()) {\n      validateCommonTlsContext(downstreamTlsContext.getCommonTlsContext(), certProviderInstances,\n          true);\n    } else {\n      throw new ResourceInvalidException(\n          \"common-tls-context is required in downstream-tls-context\");\n    }\n    if (downstreamTlsContext.hasRequireSni()) {\n      throw new ResourceInvalidException(\n          \"downstream-tls-context with require-sni is not supported\");\n    }\n    DownstreamTlsContext.OcspStaplePolicy ocspStaplePolicy = downstreamTlsContext\n        .getOcspStaplePolicy();\n    if (ocspStaplePolicy != DownstreamTlsContext.OcspStaplePolicy.UNRECOGNIZED\n        && ocspStaplePolicy != DownstreamTlsContext.OcspStaplePolicy.LENIENT_STAPLING) {\n      throw new ResourceInvalidException(\n          \"downstream-tls-context with ocsp_staple_policy value \" + ocspStaplePolicy.name()\n              + \" is not supported\");\n    }\n    return downstreamTlsContext;\n  }\n","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/xds/src/main/java/io/grpc/xds/XdsListenerResource.java#L284-L320","documentation":"A downstream TLS context must nest its configuration inside a common_tls_context; a DownstreamTlsContext without common_tls_context set cannot yield any certificates or validation parameters, so validateDownstreamTlsContext throws ResourceInvalidException. This is part of strict server-side TLS context validation before a filter chain is accepted.","triggerScenarios":"A FilterChain's transport_socket carries a DownstreamTlsContext message where the common_tls_context field is unset (hasCommonTlsContext() is false), passed through parseFilterChain into validateDownstreamTlsContext.","commonSituations":"Configs that set only fields like require_client_certificate or ocsp_staple_policy at the downstream level and forget common_tls_context; truncated control-plane templates; users porting upstream (client) TLS configs incorrectly.","solutions":["Populate common_tls_context inside downstream_tls_context with tls_certificate (or tls_certificate_sds_secret_configs) and validation_context","If using SDS, reference the certificate provider instances recognized by gRPC (matching certProviderInstances names) inside common_tls_context","Validate the LDS resource with an Envoy-compatible validator before serving it to gRPC clients"],"exampleFix":"# before\ndownstream_tls_context:\n  require_client_certificate: true\n# after\ndownstream_tls_context:\n  common_tls_context:\n    tls_certificates:\n    - certificate_chain: {filename: server.crt}\n      private_key: {filename: server.key}","handlingStrategy":"validation","validationCode":"if (fc.hasTransportSocket() && fc.getTransportSocket().hasTypedConfig()) {\n  DownstreamTlsContext tls = fc.getTransportSocket().getTypedConfig()\n      .unpack(DownstreamTlsContext.class); // may throw InvalidProtocolBufferException\n  if (!tls.hasCommonTlsContext()) {\n    throw new IllegalArgumentException(\"downstream_tls_context missing common_tls_context\");\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  listener = XdsListenerResource.parseServerSideListener(proto, ...);\n} catch (ResourceInvalidException e) {\n  if (e.getMessage().contains(\"common-tls-context is required\")) {\n    logger.warn(\"Add common_tls_context to downstream_tls_context\", e);\n  }\n}","preventionTips":["Always nest server certs and validation under common_tls_context","Reference SDS/certificate provider instance names that exist in the bootstrap","Validate TLS context protos before publishing LDS resources"],"tags":["xds","grpc","tls","missing-field"],"backgroundTag":"missing-required-config-field","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}