randomsubsetting: error switching to child of type %q: %v

Error message

randomsubsetting: error switching to child of type %q: %v

What it means

Returned by random_subsetting's UpdateClientConnState() (balancer/randomsubsetting/randomsubsetting.go:130) when gracefulswitch.ParseConfig() fails for the configured child policy. The %q is the child policy name, %v the underlying error. This means the child policy is either not registered or its own config is invalid, so the subsetting balancer cannot switch to it.

Source

Thrown at balancer/randomsubsetting/randomsubsetting.go:130

	hashSeed   uint64
	hashDigest *xxhash.Digest
}

func (b *subsettingBalancer) UpdateClientConnState(s balancer.ClientConnState) error {
	lbCfg, ok := s.BalancerConfig.(*lbConfig)
	if !ok {
		b.logger.Warningf("Received config with unexpected type %T: %v", s.BalancerConfig, s.BalancerConfig)
		return balancer.ErrBadResolverState
	}

	// 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{{lbCfg.ChildPolicy.Name: lbCfg.ChildPolicy.Config}}
	cfgJSON, _ := json.Marshal(cfg)
	parsedCfg, err := gracefulswitch.ParseConfig(cfgJSON)
	if err != nil {
		return fmt.Errorf("randomsubsetting: error switching to child of type %q: %v", lbCfg.ChildPolicy.Name, err)
	}
	b.cfg = lbCfg
	endpoints := resolver.State{
		Endpoints:     b.calculateSubset(s.ResolverState.Endpoints),
		ServiceConfig: s.ResolverState.ServiceConfig,
		Attributes:    s.ResolverState.Attributes,
	}

	return b.Balancer.UpdateClientConnState(balancer.ClientConnState{
		ResolverState:  endpoints,
		BalancerConfig: parsedCfg,
	})
}

// calculateSubset implements the subsetting algorithm, as described in A68:
// https://github.com/grpc/proposal/blob/master/A68-random-subsetting.md#subsetting-algorithm
func (b *subsettingBalancer) calculateSubset(endpoints []resolver.Endpoint) []resolver.Endpoint {
	// A helper struct to hold an endpoint and its hash.

View on GitHub (pinned to 0c51461d27)

Solutions

Ensure the child policy package is blank-imported so it self-registers (e.g. import _ "google.golang.org/grpc/balancer/roundrobin").
Verify the child policy name in the config matches a registered builder Name().
Inspect the %v for the child's own validation error and fix the child config.
Check that the grpc-go version includes the child policy you reference.

Example fix

// before: round_robin not registered (missing blank import)
import (
  _ "google.golang.org/grpc/balancer/randomsubsetting"
)
// childPolicy [{"round_robin":{}}] → gracefulswitch.ParseConfig fails

// after: also blank-import the child policy package
import (
  _ "google.golang.org/grpc/balancer/randomsubsetting"
  _ "google.golang.org/grpc/balancer/roundrobin"
)

Defensive patterns

Strategy: validation

Validate before calling

// Ensure the child policy is registered before using random_subsetting.
func ensureChildRegistered(name string) bool {
    return balancer.Get(name) != nil
}
// Usage:
// if !ensureChildRegistered("round_robin") { panic("round_robin not registered") }

Prevention

Blank-import every child policy package your config references (e.g. _ "google.golang.org/grpc/balancer/roundrobin").
At startup, assert balancer.Get(childName) != nil for each configured child.
Validate the child's own config JSON before composing it under random_subsetting.

When it happens

Trigger: After ParseConfig succeeds, UpdateClientConnState marshals the child config and calls gracefulswitch.ParseConfig(cfgJSON) at line 128. If the child policy name is unknown (not registered via balancer.Register) or the child's own ParseConfig rejects the config, the error is wrapped at line 130.

Common situations: childPolicy references a balancer whose package was not imported (blank import missing), e.g. round_robin not registered; the child's config is structurally invalid; the child policy name is misspelled; using a child policy provided by a package not linked into the binary.

Related errors

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