{"record":{"id":"69fd8c2d42199ca1","repo":"XTLS/Xray-core","slug":"balancer-s-not-found","errorCode":null,"errorMessage":"balancer '%s' not found","messagePattern":"balancer '(.+?)' not found","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"app/router/balancing_override.go","lineNumber":18,"sourceCode":"package router\n\nimport (\n\tsync \"sync\"\n\n\t\"github.com/xtls/xray-core/common/errors\"\n)\n\nfunc (r *Router) OverrideBalancer(balancer string, target string) error {\n\tvar b *Balancer\n\tfor tag, bl := range r.balancers {\n\t\tif tag == balancer {\n\t\t\tb = bl\n\t\t\tbreak\n\t\t}\n\t}\n\tif b == nil {\n\t\treturn errors.New(\"balancer '\", balancer, \"' not found\")\n\t}\n\tb.override.Put(target)\n\treturn nil\n}\n\ntype overrideSettings struct {\n\ttarget string\n}\n\ntype override struct {\n\taccess   sync.RWMutex\n\tsettings overrideSettings\n}\n\n// Get gets the override settings\nfunc (o *override) Get() string {\n\to.access.RLock()\n\tdefer o.access.RUnlock()","sourceCodeStart":1,"sourceCodeEnd":36,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/app/router/balancing_override.go#L1-L36","documentation":"Legacy OverrideBalancer walks r.balancers comparing tags and returns this error when no entry matches. Functionally identical to SetOverrideTarget's failure but built with errors.New string concatenation, so the balancer name is embedded in the message.","triggerScenarios":"Calling OverrideBalancer(balancer, target) with a name that is not any balancingRule tag; empty balancer string.","commonSituations":"Older clients or forks still calling the non-interface override path; typos in balancer names; config drift between what the client cached and what the router loaded.","solutions":["Pass the exact balancingRule tag as the balancer argument","Prefer the routing.BalancerOverrider interface (SetOverrideTarget) in new code","Reload rules/config so the balancer exists, then retry"],"exampleFix":"// before\nr.OverrideBalancer(\"bal\", \"direct\")\n\n// after\nif bo, ok := router.(routing.BalancerOverrider); ok {\n    bo.SetOverrideTarget(\"bal\", \"direct\")\n}","handlingStrategy":"validation","validationCode":"found := false\nfor t := range balancers { if t == balancer { found = true; break } }\nif !found { return fmt.Errorf(\"balancer %q not registered\", balancer) }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Migrate callers to the BalancerOverrider interface (SetOverrideTarget)","Validate the balancer name against config before calling","Unit-test override paths with both existing and missing tags"],"tags":["routing","balancer","override","legacy-api"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}