{"record":{"id":"1a7038b238a54891","repo":"XTLS/Xray-core","slug":"cannot-find-tag","errorCode":null,"errorMessage":"cannot find tag","messagePattern":"cannot find tag","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"app/router/balancing.go","lineNumber":149,"sourceCode":"\t\treturn nil, errors.New(\"outbound.Manager is not a HandlerSelector\")\n\t}\n\ttags := hs.Select(b.selectors)\n\treturn tags, nil\n}\n\n// GetPrincipleTarget implements routing.BalancerPrincipleTarget\nfunc (r *Router) GetPrincipleTarget(tag string) ([]string, error) {\n\tif b, ok := r.balancers[tag]; ok {\n\t\tif s, ok := b.strategy.(BalancingPrincipleTarget); ok {\n\t\t\tcandidates, err := b.SelectOutbounds()\n\t\t\tif err != nil {\n\t\t\t\treturn nil, errors.New(\"unable to select outbounds\").Base(err)\n\t\t\t}\n\t\t\treturn s.GetPrincipleTarget(candidates), nil\n\t\t}\n\t\treturn nil, errors.New(\"unsupported GetPrincipleTarget\")\n\t}\n\treturn nil, errors.New(\"cannot find tag\")\n}\n\n// SetOverrideTarget implements routing.BalancerOverrider\nfunc (r *Router) SetOverrideTarget(tag, target string) error {\n\tif b, ok := r.balancers[tag]; ok {\n\t\tb.override.Put(target)\n\t\treturn nil\n\t}\n\treturn errors.New(\"cannot find tag\")\n}\n\n// GetOverrideTarget implements routing.BalancerOverrider\nfunc (r *Router) GetOverrideTarget(tag string) (string, error) {\n\tif b, ok := r.balancers[tag]; ok {\n\t\treturn b.override.Get(), nil\n\t}\n\treturn \"\", errors.New(\"cannot find tag\")\n}","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/app/router/balancing.go#L131-L167","documentation":"Generic lookup miss in the router's balancer map: GetPrincipleTarget, SetOverrideTarget, and GetOverrideTarget all return this when the tag argument names no registered balancer. It is purely a 'no such balancer' error — the tag exists neither in r.balancers (built from routing config) nor anywhere the API accepts.","triggerScenarios":"Calling router balancer override/inspection APIs with a misspelled or unconfigured balancerTag — e.g. the API command SetOverrideTarget(\"bl\", ...) when the routing config defines balancer tag \"bal\", or querying before routing/balancers finished initializing.","commonSituations":"Automation scripts or admin panels guessing balancer tags; renames in routing config breaking external tooling that hardcodes the old tag; API calls racing instance startup before the router feature registers balancers.","solutions":["List the configured balancers from the routing config and use the exact tag string in API calls.","After renaming a balancer, update every external script/panel that references the old tag.","If the error appears right after startup, retry once the instance reports the router feature ready."],"exampleFix":"// before (api call)\nrouter.SetOverrideTarget(\"bl\", \"node-2\") // no balancer tagged \"bl\"\n\n// after\nrouter.SetOverrideTarget(\"bal\", \"node-2\") // matches { \"balancers\": [ { \"tag\": \"bal\", ... } ] }","handlingStrategy":"validation","validationCode":"// Verify the balancer tag against routing config before API calls\ntags := map[string]bool{}\nfor _, b := range cfg.Routing.Balancers { tags[b.Tag] = true }\nif !tags[queryTag] { return fmt.Errorf(\"unknown balancer tag %q\", queryTag) }","typeGuard":"func isKnownBalancerTag(cfg RoutingConfig, tag string) bool {\n    for _, b := range cfg.Balancers { if b.Tag == tag { return true } }\n    return false\n}","tryCatchPattern":"if err := router.SetOverrideTarget(tag, target); err != nil {\n    if strings.Contains(err.Error(), \"cannot find tag\") {\n        return fmt.Errorf(\"balancer %q not in configured routing balancers; check spelling\", tag)\n    }\n    return err\n}","preventionTips":["Drive admin tooling from the live config, not hardcoded tag strings","Update scripts/panels after any balancer rename","Retry once after startup completes to rule out initialization races"],"tags":["go","xray","routing","balancer","api","tag"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}