{"record":{"id":"599852c6a8d4fbcc","repo":"t8y2/dbx","slug":"dcawareroundrobinpolicy-requires-localdatacenter","errorCode":null,"errorMessage":"DCAwareRoundRobinPolicy requires localdatacenter","messagePattern":"DCAwareRoundRobinPolicy requires localdatacenter","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agents/drivers/cassandra-go/config.go","lineNumber":636,"sourceCode":"\nfunc applyLoadBalancingPolicy(cluster *gocql.ClusterConfig, config cassandraConfig) error {\n\tpolicy := config.loadBalancingPolicy\n\tif policy == \"\" {\n\t\tpolicy = \"default\"\n\t}\n\tswitch policy {\n\tcase \"default\":\n\t\tif config.localDatacenter == \"\" {\n\t\t\treturn nil\n\t\t}\n\t\tcluster.PoolConfig.HostSelectionPolicy = gocql.TokenAwareHostPolicy(\n\t\t\tgocql.DCAwareRoundRobinPolicy(config.localDatacenter),\n\t\t)\n\tcase \"round_robin\":\n\t\tcluster.PoolConfig.HostSelectionPolicy = gocql.RoundRobinHostPolicy()\n\tcase \"dc_aware\":\n\t\tif config.localDatacenter == \"\" {\n\t\t\treturn fmt.Errorf(\"DCAwareRoundRobinPolicy requires localdatacenter\")\n\t\t}\n\t\tcluster.PoolConfig.HostSelectionPolicy = gocql.DCAwareRoundRobinPolicy(config.localDatacenter)\n\tcase \"token_aware\":\n\t\tfallback := gocql.RoundRobinHostPolicy()\n\t\tif config.localDatacenter != \"\" {\n\t\t\tfallback = gocql.DCAwareRoundRobinPolicy(config.localDatacenter)\n\t\t}\n\t\tcluster.PoolConfig.HostSelectionPolicy = gocql.TokenAwareHostPolicy(fallback)\n\tdefault:\n\t\treturn fmt.Errorf(\"unsupported Cassandra loadbalancing policy: %s\", policy)\n\t}\n\treturn nil\n}\n\nfunc normalizeOptionName(value string) string {\n\treturn strings.NewReplacer(\"_\", \"\", \"-\", \"\", \".\", \"\").Replace(strings.ToLower(strings.TrimSpace(value)))\n}\n","sourceCodeStart":618,"sourceCodeEnd":654,"githubUrl":"https://github.com/t8y2/dbx/blob/c0390bff16418b651f4728520d99adf8ce48829a/agents/drivers/cassandra-go/config.go#L618-L654","documentation":"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).","triggerScenarios":"Setting loadBalancing policy to 'dc_aware' without also setting localDatacenter in the Cassandra config.","commonSituations":"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.","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'"],"exampleFix":"// before\nloadBalancing: \"dc_aware\"\n// after\nloadBalancing: \"dc_aware\"\nlocalDatacenter: \"datacenter1\"","handlingStrategy":"validation","validationCode":"if strings.EqualFold(cfg.LoadBalancing, \"dc_aware\") && strings.TrimSpace(cfg.LocalDatacenter) == \"\" {\n    return fmt.Errorf(\"loadBalancing=dc_aware requires localDatacenter to be set\")\n}","typeGuard":"func dcAwareRequiresLocalDC(policy, localDC string) bool {\n    return policy != \"dc_aware\" || localDC != \"\"\n}","tryCatchPattern":"if err := clusterConfig(cfg); err != nil {\n    if strings.Contains(err.Error(), \"DCAwareRoundRobinPolicy requires localdatacenter\") {\n        return fmt.Errorf(\"config: set localDatacenter to your Cassandra DC name (see nodetool ring): %w\", err)\n    }\n    return err\n}","preventionTips":["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"],"tags":["cassandra","config","load-balancing"],"backgroundTag":"missing-required-config","analyzedSha":"c0390bff16418b651f4728520d99adf8ce48829a","analyzedAt":"2026-09-05T23:05:10.900Z","contentChangedAt":"2026-09-05T23:05:10.900Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}