security configuration on the client-side does not contain…

Error message

security configuration on the client-side does not contain root certificate provider instance name

What it means

Thrown by securityConfigFromCommonTLSContext on the client side when the parsed SecurityConfig neither uses system roots (UseSystemRootCerts==false) nor has a RootInstanceName. grpc-go needs either a root certificate provider instance name or system root certs to validate the server's certificate. The error surfaces while unmarshaling a CDS cluster's upstream TLS context after both new and deprecated field paths failed to supply a validation/ root context.

Solutions

Ensure the CDS UpstreamTlsContext provides a validation context with a non-empty certificate_provider_instance instance_name, or set system_root_certs=true to fall back to the OS trust store.
Check the deprecated combined_validation_context.default_validation_context path still populates the provider instance if the control plane uses deprecated fields.
Verify the xDS bootstrap certificate_providers map registers the root provider name the control plane references.
Confirm the control-plane-side CA/secret rotation pipeline still emits the root cert to SDS for that provider name.

Example fix

// before: cluster has TLS but no validation context
//   transport_socket: { name: "tls", typed_config: { common_tls_context: {} } }
//
// after: supply a root cert provider instance name
//   transport_socket: {
//     name: "tls",
//     typed_config: {
//       common_tls_context: {
//         validation_context: {
//           certificate_provider_instance: { instance_name: "roots" }
//         }
//       }
//     }
//   }

Defensive patterns

Strategy: validation

Try / catch

Handle in the xDS watcher callback (WatchCluster) by logging the cluster name and version; alert operations that the cluster's validation context is missing. No client-side retry will help until the control plane re-sends a valid config.

Prevention

Policy-check all CDS UpstreamTlsContext resources to ensure validation_context or system_root_certs is populated.
Maintain a bootstrap template that always registers a default root cert provider.
During migrations between SDS field names, run an integration test that asserts RootInstanceName is non-empty before promotion.

When it happens

Trigger: A CDS UpstreamTlsContext is sent where combined_validation_context / validation_context / validation_context_sds_secret_config do not resolve to a non-empty certificate_provider_instance instance_name, and the system_root_certs field is not set. Equivalent deprecated fields (validation_context_certificate_provider_instance) are also empty.

Common situations: Control-plane config for a cluster enables TLS but omits the root/CA validation context. Bootstrap file lacks a root cert provider registration. Migration between SDS field names dropped the root provider name. Private CA setup where the operator forgot to attach the root cert bundle provider.

Understand the failure class

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

Related errors

AI-assisted analysis of grpc/grpc-go@0c51461d27 (2026-08-11). Data as JSON: /api/errors/09c16fa7f5f294ab. Report an issue: GitHub.

Appendix: source

Thrown at internal/xds/xdsclient/xdsresource/unmarshal_cds.go:418

	sc, err1 := securityConfigFromCommonTLSContextUsingNewFields(common, server)
	if sc == nil || sc.Equal(&SecurityConfig{}) {
		var err error
		sc, err = securityConfigFromCommonTLSContextWithDeprecatedFields(common, server)
		if err != nil {
			// Retain the validation error from using the new fields.
			return nil, errors.Join(err1, fmt.Errorf("failed to parse config using deprecated fields: %v", err))
		}
	}
	if sc != nil {
		// sc == nil is a valid case where the control plane has not sent us any
		// security configuration. xDS creds will use fallback creds.
		if server {
			if sc.IdentityInstanceName == "" {
				return nil, errors.New("security configuration on the server-side does not contain identity certificate provider instance name")
			}
		} else {
			if !sc.UseSystemRootCerts && sc.RootInstanceName == "" {
				return nil, errors.New("security configuration on the client-side does not contain root certificate provider instance name")
			}
		}
	}
	return sc, nil
}

func securityConfigFromCommonTLSContextWithDeprecatedFields(common *v3tlspb.CommonTlsContext, server bool) (*SecurityConfig, error) {
	// The `CommonTlsContext` contains a
	// `tls_certificate_certificate_provider_instance` field of type
	// `CertificateProviderInstance`, which contains the provider instance name
	// and the certificate name to fetch identity certs.
	sc := &SecurityConfig{}
	if identity := common.GetTlsCertificateCertificateProviderInstance(); identity != nil {
		sc.IdentityInstanceName = identity.GetInstanceName()
		sc.IdentityCertName = identity.GetCertificateName()
	}

	// The `CommonTlsContext` contains a `validation_context_type` field which

View on GitHub (pinned to 0c51461d27)