DCAwareRoundRobinPolicy requires localdatacenter

Error message

DCAwareRoundRobinPolicy requires localdatacenter

What it means

The dc_aware load-balancing policy requires knowing which datacenter is 'local' so it can prefer hosts there. If config.localDatacenter is empty, applyLoadBalancingPolicy refuses to build a DCAwareRoundRobinPolicy because it would behave incorrectly (treating no DC as local).

Source

Thrown at agents/drivers/cassandra-go/config.go:636

func applyLoadBalancingPolicy(cluster *gocql.ClusterConfig, config cassandraConfig) error {
	policy := config.loadBalancingPolicy
	if policy == "" {
		policy = "default"
	}
	switch policy {
	case "default":
		if config.localDatacenter == "" {
			return nil
		}
		cluster.PoolConfig.HostSelectionPolicy = gocql.TokenAwareHostPolicy(
			gocql.DCAwareRoundRobinPolicy(config.localDatacenter),
		)
	case "round_robin":
		cluster.PoolConfig.HostSelectionPolicy = gocql.RoundRobinHostPolicy()
	case "dc_aware":
		if config.localDatacenter == "" {
			return fmt.Errorf("DCAwareRoundRobinPolicy requires localdatacenter")
		}
		cluster.PoolConfig.HostSelectionPolicy = gocql.DCAwareRoundRobinPolicy(config.localDatacenter)
	case "token_aware":
		fallback := gocql.RoundRobinHostPolicy()
		if config.localDatacenter != "" {
			fallback = gocql.DCAwareRoundRobinPolicy(config.localDatacenter)
		}
		cluster.PoolConfig.HostSelectionPolicy = gocql.TokenAwareHostPolicy(fallback)
	default:
		return fmt.Errorf("unsupported Cassandra loadbalancing policy: %s", policy)
	}
	return nil
}

func normalizeOptionName(value string) string {
	return strings.NewReplacer("_", "", "-", "", ".", "").Replace(strings.ToLower(strings.TrimSpace(value)))
}

View on GitHub (pinned to c0390bff16)

Solutions

Set the localDatacenter option to the name of your local datacenter (must match the DC name reported by the cluster)
Use system.local / nodetool ring to confirm the exact DC name — it is case-sensitive
If you don't need DC awareness, switch loadBalancing to 'round_robin'

Example fix

// before
loadBalancing: "dc_aware"
// after
loadBalancing: "dc_aware"
localDatacenter: "datacenter1"

Defensive patterns

Strategy: validation

Validate before calling

if strings.EqualFold(cfg.LoadBalancing, "dc_aware") && strings.TrimSpace(cfg.LocalDatacenter) == "" {
    return fmt.Errorf("loadBalancing=dc_aware requires localDatacenter to be set")
}

Type guard

func dcAwareRequiresLocalDC(policy, localDC string) bool {
    return policy != "dc_aware" || localDC != ""
}

Try / catch

if err := clusterConfig(cfg); err != nil {
    if strings.Contains(err.Error(), "DCAwareRoundRobinPolicy requires localdatacenter") {
        return fmt.Errorf("config: set localDatacenter to your Cassandra DC name (see nodetool ring): %w", err)
    }
    return err
}

Prevention

Always pair dc_aware with an explicit localDatacenter in your config templates
Verify the DC name matches the cluster exactly (case-sensitive, from system.local)
For single-DC dev environments prefer round_robin to avoid the requirement

When it happens

Trigger: Setting loadBalancing policy to 'dc_aware' without also setting localDatacenter in the Cassandra config.

Common situations: Multi-datacenter clusters where the operator enables dc_aware routing but forgets the local DC option; config files copied from single-DC setups that never specified a DC.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/599852c6a8d4fbcc. Report an issue: GitHub.