grpc/grpc-go · error

received Cluster resource that contains invalid security con

Error message

received Cluster resource that contains invalid security config: %v

What it means

The cluster_impl balancer processes the security configuration from the cluster resource by creating certificate provider plugins and building HandshakeInfo. This error wraps any failure from handleSecurityConfig, which includes building identity/root cert providers, setting up SAN matchers, and configuring SNI. The security config controls mTLS and certificate validation for the cluster's connections.

Source

Thrown at internal/xds/balancer/clusterimpl/clusterimpl.go:434

		c := xdsclient.FromResolverState(s.ResolverState)
		if c == nil {
			return balancer.ErrBadResolverState
		}
		b.xdsClient = c
	}

	xdsConfig := xdsresource.XDSConfigFromResolverState(s.ResolverState)
	if xdsConfig == nil {
		b.logger.Warningf("Received balancer config with no xDS config")
		return balancer.ErrBadResolverState
	}
	clusterCfg := xdsConfig.Clusters[newConfig.Cluster]
	clusterUpdate := clusterCfg.Config.Cluster
	if err := b.handleSecurityConfig(clusterUpdate.SecurityCfg); err != nil {
		// If the security config is invalid, for example, if the provider
		// instance is not found in the bootstrap config, we need to put the
		// channel in transient failure.
		return fmt.Errorf("received Cluster resource that contains invalid security config: %v", err)

	}
	// Update load reporting config. This needs to be done before updating the
	// child policy because we need the loadStore from the updated client to be
	// passed to the ccWrapper, so that the next picker from the child policy
	// will pick up the new loadStore.
	if err := b.updateLoadStore(clusterUpdate); err != nil {
		return err
	}

	// Build config for the gracefulswitch balancer. It is safe to ignore JSON
	// marshaling errors here, since the config was already validated as part of
	// ParseConfig().
	cfg := []map[string]any{{newConfig.ChildPolicy.Name: newConfig.ChildPolicy.Config}}
	cfgJSON, _ := json.Marshal(cfg)
	parsedCfg, err := gracefulswitch.ParseConfig(cfgJSON)
	if err != nil {
		return err

View on GitHub (pinned to 03255a9237)

Solutions

1. Verify the xDS bootstrap config's certificate_providers section contains entries for all instance names referenced by cluster security configs
2. Check that certificate and key files exist and are readable at the paths in the bootstrap config
3. Compare the security config's provider instance names with the bootstrap config's provider names — they must match exactly
4. If not using xDS credentials, ensure the bootstrap or dial options don't enable xdsCredentials unnecessarily
5. Enable GRPC_GO_LOG_SEVERITY=info to see the wrapped error from handleSecurityConfig for the specific root cause

Example fix

// before: bootstrap missing the provider referenced by cluster security config
// cluster security config references "mtls-identity" but bootstrap only has "default"
// after: add the missing provider to bootstrap
{"certificate_providers": {
  "default": {...},
  "mtls-identity": {"plugin_name": "file_watcher", "config": {"certificate_file": "/etc/certs/identity.crt", "private_key_file": "/etc/certs/identity.key"}}
}}

// Verify security config providers exist in bootstrap before relying on them
func validateSecurityProviders(bootstrapPath, securityInstanceName string) error {
    data, err := os.ReadFile(bootstrapPath)
    if err != nil { return err }
    var cfg struct {
        CertProviders map[string]json.RawMessage `json:"certificate_providers"`
    }
    json.Unmarshal(data, &cfg)
    if _, ok := cfg.CertProviders[securityInstanceName]; !ok {
        return fmt.Errorf("security provider %q not found in bootstrap config", securityInstanceName)
    }
    return nil
}

// Channel enters TRANSIENT_FAILURE for the affected cluster
if conn.GetState() == connectivity.TransientFailure {
    // check logs for 'invalid security config'
    // verify bootstrap providers match cluster security config
}

When it happens

Trigger: Triggered in cluster_impl's UpdateClientConnState when handleSecurityConfig(clusterUpdate.SecurityCfg) returns an error. The security config comes from the CDS resource. Failures include: certificate provider build errors (file not found, cert/key mismatch), missing provider instance in bootstrap config, or the security config references a provider instance name not configured in the bootstrap.

Common situations: The xDS bootstrap config doesn't have a certificate provider matching the instance name in the cluster's security config; the cluster resource references a fallback security config but xDS credentials are not in use; certificate files are missing or unreadable; the SAN matchers in the security config are malformed; the management server sends a security config that doesn't match any bootstrap provider.

Related errors

• xds: failed to get security plugin instance (%+v): %v
• UpstreamTlsContext in CDS response does not contain a Common
• security configuration on the server-side does not contain i
• security configuration on the client-side does not contain r
• DownstreamTlsContext in LDS response does not contain a Comm

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