DownstreamTlsContext in LDS response does not contain a Comm

Error message

DownstreamTlsContext in LDS response does not contain a CommonTlsContext

What it means

Returned when unmarshalling a filter chain's DownstreamTlsContext (unmarshal_lds.go:353-354) if the typed config parses but its common_tls_context field is nil. The server-side security handler needs a CommonTlsContext to build the downstream (server) TLS config; a DownstreamTlsContext with only require_client_certificate or session fields but no common_tls_context is rejected.

Source

Thrown at internal/xds/xdsclient/xdsresource/unmarshal_lds.go:354

	if name := ts.GetName(); name != transportSocketName {
		return emptyFilterChain, fmt.Errorf("transport_socket field has unexpected name: %s", name)
	}
	tc := ts.GetTypedConfig()
	if typeURL := tc.GetTypeUrl(); typeURL != version.V3DownstreamTLSContextURL {
		return emptyFilterChain, fmt.Errorf("transport_socket missing typed_config or wrong type_url: %q", typeURL)
	}
	downstreamCtx := &v3tlspb.DownstreamTlsContext{}
	if err := proto.Unmarshal(tc.GetValue(), downstreamCtx); err != nil {
		return emptyFilterChain, fmt.Errorf("failed to unmarshal DownstreamTlsContext in LDS response: %v", err)
	}
	if downstreamCtx.GetRequireSni().GetValue() {
		return emptyFilterChain, fmt.Errorf("require_sni field set to true in DownstreamTlsContext message: %v", downstreamCtx)
	}
	if downstreamCtx.GetOcspStaplePolicy() != v3tlspb.DownstreamTlsContext_LENIENT_STAPLING {
		return emptyFilterChain, fmt.Errorf("ocsp_staple_policy field set to unsupported value in DownstreamTlsContext message: %v", downstreamCtx)
	}
	if downstreamCtx.GetCommonTlsContext() == nil {
		return emptyFilterChain, errors.New("DownstreamTlsContext in LDS response does not contain a CommonTlsContext")
	}
	sc, err := securityConfigFromCommonTLSContext(downstreamCtx.GetCommonTlsContext(), true)
	if err != nil {
		return emptyFilterChain, err
	}
	if sc != nil {
		sc.RequireClientCert = downstreamCtx.GetRequireClientCertificate().GetValue()
		if sc.RequireClientCert && sc.RootInstanceName == "" {
			return emptyFilterChain, errors.New("security configuration on the server-side does not contain root certificate provider instance name, but require_client_cert field is set")
		}
		fcc.SecurityCfg = sc
	}
	return fcc, nil
}

// dstPrefixEntry wraps DestinationPrefixEntry to track build state.
type dstPrefixEntry struct {
	entry         DestinationPrefixEntry

View on GitHub (pinned to 03255a9237)

Solutions

Populate DownstreamTlsContext.common_tls_context with identity (and root, if mTLS) certificate provider config.
If TLS is not intended for that filter chain, remove the transport_socket so no DownstreamTlsContext is parsed.
Inspect the raw listener/filter-chain resource and confirm common_tls_context is present.

Example fix

// before
//   downstream_tls_context: { require_client_certificate: true }  // no common_tls_context
// after
//   downstream_tls_context: {
//     common_tls_context: { tls_certificate_certificate_provider_instance: {...}, validation_context: {...} },
//     require_client_certificate: true
//   }

Defensive patterns

Strategy: validation

Validate before calling

func downstreamTLSHasCommonCtx(dts *v3tlspb.DownstreamTlsContext) bool {
    return dts != nil && dts.GetCommonTlsContext() != nil
}

Type guard

func isCompleteDownstreamTLS(dts *v3tlspb.DownstreamTlsContext) bool {
    return downstreamTLSHasCommonCtx(dts)
}

Prevention

Always populate common_tls_context in DownstreamTlsContext for gRPC.
If TLS is not needed, remove the transport_socket from the filter chain.
Validate listener security fixtures in tests before publishing.

When it happens

Trigger: An LDS filter chain provides a transport_socket with typed_config DownstreamTlsContext whose common_tls_context is unset. After proto.Unmarshal, the nil check at line 353 fires and the filter chain is rejected.

Common situations: Control plane sends a partial DownstreamTlsContext (e.g. only require_client_certificate set); templating bug; a fixture missing the TLS context body.

Related errors

AI-assisted analysis of grpc/grpc-go@03255a9237 (2026-08-07). Data as JSON: /api/errors/1d62a49b5910c179. Report an issue: GitHub.