XTLS/Xray-core · error

balancer %s not found

Error message

balancer %s not found

What it means

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.

Source

Thrown at app/router/router.go:84

			RuleTag:   rule.GetRuleTag(),
		}
		if wh := rule.GetWebhook(); wh != nil {
			notifier, err := NewWebhookNotifier(wh)
			if err != nil {
				r.closeWebhooks()
				return err
			}
			rr.Webhook = notifier
		}
		btag := rule.GetBalancingTag()
		if len(btag) > 0 {
			brule, found := r.balancers[btag]
			if !found {
				if rr.Webhook != nil {
					rr.Webhook.Close()
				}
				r.closeWebhooks()
				return errors.New("balancer ", btag, " not found")
			}
			rr.Balancer = brule
		}
		r.rules = append(r.rules, rr)
	}

	return nil
}

// PickRoute implements routing.Router.
func (r *Router) PickRoute(ctx routing.Context) (routing.Route, error) {
	originalCtx := ctx
	rule, ctx, err := r.pickRouteInternal(ctx)
	if err != nil {
		return nil, err
	}
	tag, err := rule.GetTag()
	if err != nil {

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Add a balancingRule whose tag exactly matches the rule's balancerTag
2. Fix the spelling/case of balancerTag in the referencing rule
3. Remove the rule if the balancer was intentionally deleted

Example fix

// before
"rules": [{ "type": "field", "balancerTag": "blc", "network": "tcp,udp" }]
// no balancingRule named blc

// after
"balancingRule": [{ "tag": "blc", "selector": ["proxy"], "strategy": { "type": "random" } }],
"rules": [{ "type": "field", "balancerTag": "blc", "network": "tcp,udp" }]

func checkBalancerRefs(cfg *router.Config) error {
    tags := map[string]bool{}
    for _, b := range cfg.BalancingRule { tags[b.Tag] = true }
    for _, r := range cfg.Rule {
        if t := r.GetBalancerTag(); t != "" && !tags[t] {
            return fmt.Errorf("rule references undefined balancerTag %q", t)
        }
    }
    return nil
}

When it happens

Trigger: A rule withBalancer balancerTag=X where no balancingRule with tag X exists in the same config; case-mismatched tags.

Common situations: Renaming a balancer but not the rules pointing at it; JSON edits where the rule was added first; split config files loaded separately.

Related errors

• not a StrategyLeastLoadConfig
• unrecognized balancer type
• duplicate balancer tag
• balancing strategy returns empty tag
• unable to select outbounds

AI-assisted analysis of XTLS/Xray-core@7d214f8b09 (2026-08-15). Data as JSON: /api/errors/48ec2c256371fe7b. Report an issue: GitHub.