{"record":{"id":"48ec2c256371fe7b","repo":"XTLS/Xray-core","slug":"balancer-s-not-found-48ec2c","errorCode":null,"errorMessage":"balancer %s not found","messagePattern":"balancer (.+?) not found","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"app/router/router.go","lineNumber":84,"sourceCode":"\t\t\tRuleTag:   rule.GetRuleTag(),\n\t\t}\n\t\tif wh := rule.GetWebhook(); wh != nil {\n\t\t\tnotifier, err := NewWebhookNotifier(wh)\n\t\t\tif err != nil {\n\t\t\t\tr.closeWebhooks()\n\t\t\t\treturn err\n\t\t\t}\n\t\t\trr.Webhook = notifier\n\t\t}\n\t\tbtag := rule.GetBalancingTag()\n\t\tif len(btag) > 0 {\n\t\t\tbrule, found := r.balancers[btag]\n\t\t\tif !found {\n\t\t\t\tif rr.Webhook != nil {\n\t\t\t\t\trr.Webhook.Close()\n\t\t\t\t}\n\t\t\t\tr.closeWebhooks()\n\t\t\t\treturn errors.New(\"balancer \", btag, \" not found\")\n\t\t\t}\n\t\t\trr.Balancer = brule\n\t\t}\n\t\tr.rules = append(r.rules, rr)\n\t}\n\n\treturn nil\n}\n\n// PickRoute implements routing.Router.\nfunc (r *Router) PickRoute(ctx routing.Context) (routing.Route, error) {\n\toriginalCtx := ctx\n\trule, ctx, err := r.pickRouteInternal(ctx)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\ttag, err := rule.GetTag()\n\tif err != nil {","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/app/router/router.go#L66-L102","documentation":"During initial rule resolution, a routing rule references a balancingRule tag that is not in the built balancers map. Webhooks opened so far are closed and startup/reload aborts, keeping config atomic.","triggerScenarios":"A rule withBalancer balancerTag=X where no balancingRule with tag X exists in the same config; case-mismatched tags.","commonSituations":"Renaming a balancer but not the rules pointing at it; JSON edits where the rule was added first; split config files loaded separately.","solutions":["Add a balancingRule whose tag exactly matches the rule's balancerTag","Fix the spelling/case of balancerTag in the referencing rule","Remove the rule if the balancer was intentionally deleted"],"exampleFix":"// before\n\"rules\": [{ \"type\": \"field\", \"balancerTag\": \"blc\", \"network\": \"tcp,udp\" }]\n// no balancingRule named blc\n\n// after\n\"balancingRule\": [{ \"tag\": \"blc\", \"selector\": [\"proxy\"], \"strategy\": { \"type\": \"random\" } }],\n\"rules\": [{ \"type\": \"field\", \"balancerTag\": \"blc\", \"network\": \"tcp,udp\" }]","handlingStrategy":"validation","validationCode":"func checkBalancerRefs(cfg *router.Config) error {\n    tags := map[string]bool{}\n    for _, b := range cfg.BalancingRule { tags[b.Tag] = true }\n    for _, r := range cfg.Rule {\n        if t := r.GetBalancerTag(); t != \"\" && !tags[t] {\n            return fmt.Errorf(\"rule references undefined balancerTag %q\", t)\n        }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run the cross-reference check above on every config change","Rename balancers and their referencing rules atomically in one edit","Use config check mode (xray run -test) before restart"],"tags":["routing","balancer","configuration","startup"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}