error parsing loadBalancingConfig for policy %q: %v

Error message

error parsing loadBalancingConfig for policy %q: %v

What it means

This error occurs when a registered load balancing policy's ConfigParser.ParseConfig rejects the provided JSON config. The balancer was found in the registry, but its custom parsing logic flagged the config as invalid for that specific policy (e.g., bad field values for round_robin, weighted_target, or rls).

Source

Thrown at internal/serviceconfig/serviceconfig.go:116

		if builder == nil {
			// If the balancer is not registered, move on to the next config.
			// This is not an error.
			continue
		}
		bc.Name = name

		parser, ok := builder.(balancer.ConfigParser)
		if !ok {
			if string(jsonCfg) != "{}" {
				logger.Warningf("non-empty balancer configuration %q, but balancer does not implement ParseConfig", string(jsonCfg))
			}
			// Stop at this, though the builder doesn't support parsing config.
			return nil
		}

		cfg, err := parser.ParseConfig(jsonCfg)
		if err != nil {
			return fmt.Errorf("error parsing loadBalancingConfig for policy %q: %v", name, err)
		}
		bc.Config = cfg
		return nil
	}
	// This is reached when the for loop iterates over all entries, but didn't
	// return. This means we had a loadBalancingConfig slice but did not
	// encounter a registered policy. The config is considered invalid in this
	// case.
	return fmt.Errorf("invalid loadBalancingConfig: no supported policies found in %v", names)
}

// MethodConfig defines the configuration recommended by the service providers for a
// particular method.
type MethodConfig struct {
	// WaitForReady indicates whether RPCs sent to this method should wait until
	// the connection is ready by default (!failfast). The value specified via the
	// gRPC client API will override the value set here.
	WaitForReady *bool

View on GitHub (pinned to 03255a9237)

Solutions

Check the inner error (%v) to identify which field/value the balancer rejected.
Align the balancer config JSON with the schema expected by the registered balancer version in your client.
Upgrade or downgrade the gRPC client to match the config format emitted by your control plane.
If using a custom balancer, review its ParseConfig for the validation rule that triggered the error.

Example fix

// before (broken): weighted_target with invalid child config
{"weighted_target": {"targets": {"a": {"weight": -1, "childPolicy": [{}]}}}}

// after (valid): non-negative weight
{"weighted_target": {"targets": {"a": {"weight": 1, "childPolicy": [{"pick_first": {}}]}}}}

Defensive patterns

Strategy: try-catch

Try / catch

var bc serviceconfig.BalancerConfig
if err := json.Unmarshal(raw, &bc); err != nil {
    if strings.Contains(err.Error(), "error parsing loadBalancingConfig") {
        // log inner error, check balancer version compatibility
        log.Printf("balancer config parse failed: %v — check policy %q schema", err, bc.Name)
        return nil // skip applying this config
    }
    return err
}

Prevention

Keep client gRPC version in sync with the balancer config schema version.
Test balancer configs against the exact client library version in production.
Import only the balancers you need and verify their config schemas in documentation.

When it happens

Trigger: A service config loadBalancingConfig entry references a registered balancer (e.g., "weighted_target") but the config JSON for that balancer is structurally invalid per its own ParseConfig implementation — for example, negative weights, missing required fields, or malformed sub-configs.

Common situations: xDS control plane emits a balancer config with wrong field types or values, version mismatch between the control plane config schema and the gRPC client library (newer config format sent to older client), or custom balancer with strict parsing rejecting unexpected fields.

Related errors

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