grpc/grpc-go · error

failed to push new configuration %v to child %q: %v

Error message

failed to push new configuration %v to child %q: %v

What it means

The cluster manager pushes new resolver state and balancer config to each child balancer via the balancer group. This error wraps any rejection from a child balancer's UpdateClientConnState. Each child is an independent sub-balancer handling a specific route's cluster. The error is isolated to one child — others with good configs continue serving RPCs.

Source

Thrown at internal/xds/balancer/clustermanager/clustermanager.go:144

				// new child policy.
				lbCfg, err = balancergroup.ParseConfig(cfgJSON)
				if err != nil {
					retErr = fmt.Errorf("failed to parse load balancing policy for child %q: %v", childName, err)
					b.setErrorPickerForChild(childName, retErr)
					continue
				}
			}
		}

		if err := b.bg.UpdateClientConnState(childName, balancer.ClientConnState{
			ResolverState: resolver.State{
				Endpoints:     endpointsSplit[childName],
				ServiceConfig: s.ResolverState.ServiceConfig,
				Attributes:    s.ResolverState.Attributes,
			},
			BalancerConfig: lbCfg,
		}); err != nil {
			retErr = fmt.Errorf("failed to push new configuration %v to child %q: %v", childCfg.ChildPolicy.Config, childName, err)
			b.setErrorPickerForChild(childName, retErr)
		}

		// Picker update is sent to the parent ClientConn only after the
		// new child policy returns a picker. So, there is no need to
		// set needUpdateStateOnResume to true here.
	}

	b.children = newConfig.Children

	// If multiple sub-balancers run into errors, we will return only the last
	// one, which is still good enough, since the grpc channel will anyways
	// return this error as balancer.ErrBadResolver to the name resolver,
	// resulting in re-resolution attempts.
	return retErr

	// Adding or removing a sub-balancer will result in the
	// needUpdateStateOnResume bit to true which results in a picker update once

View on GitHub (pinned to 03255a9237)

Solutions

1. Enable GRPC_GO_LOG_SEVERITY=info to see the child balancer's own error logs (the child name and wrapped error are in the message)
2. Verify the route configuration and cluster resources on the management server are consistent and complete
3. Check that the failing child's cluster has valid endpoints and security config
4. The error triggers re-resolution, so transient issues may self-heal — monitor whether it persists
5. Other children continue working, so verify if the failing child's route is critical for your application

// No direct pre-validation; the child balancer validates internally
// Ensure all downstream balancers and clusters are properly configured

// The error triggers re-resolution; monitor for self-healing
// Other children continue serving RPCs
if conn.GetState() == connectivity.TransientFailure {
    // check logs for which child failed and why
    // re-resolution may fix transient issues automatically
}

When it happens

Trigger: Triggered in cluster_manager's UpdateClientConnState when b.bg.UpdateClientConnState(childName, ...) returns an error. The child balancer (typically cluster_impl or CDS) validates the config and endpoints before accepting. Rejection causes the channel to request re-resolution via ErrBadResolverState.

Common situations: The child balancer (cluster_impl, CDS, etc.) encounters an internal error processing the config (e.g., invalid security config, missing cluster resource); the endpoints for a child's cluster are empty or malformed; the child balancer's own child policy rejects the configuration; a resource-not-found error from the xDS client for a specific cluster.

Related errors

• failed to push config to child policy: %v
• missing server_listener_resource_name_template in the bootst
• no priority is provided, all priorities are removed
• xds_wrr_locality: invalid LBConfig: child policy field must
• input StringMatcher proto is nil

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