XTLS/Xray-core · error

balancer '%s' not found

Error message

balancer '%s' not found

What it means

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.

Source

Thrown at app/router/balancing_override.go:18

package router

import (
	sync "sync"

	"github.com/xtls/xray-core/common/errors"
)

func (r *Router) OverrideBalancer(balancer string, target string) error {
	var b *Balancer
	for tag, bl := range r.balancers {
		if tag == balancer {
			b = bl
			break
		}
	}
	if b == nil {
		return errors.New("balancer '", balancer, "' not found")
	}
	b.override.Put(target)
	return nil
}

type overrideSettings struct {
	target string
}

type override struct {
	access   sync.RWMutex
	settings overrideSettings
}

// Get gets the override settings
func (o *override) Get() string {
	o.access.RLock()
	defer o.access.RUnlock()

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Pass the exact balancingRule tag as the balancer argument
2. Prefer the routing.BalancerOverrider interface (SetOverrideTarget) in new code
3. Reload rules/config so the balancer exists, then retry

Example fix

// before
r.OverrideBalancer("bal", "direct")

// after
if bo, ok := router.(routing.BalancerOverrider); ok {
    bo.SetOverrideTarget("bal", "direct")
}

found := false
for t := range balancers { if t == balancer { found = true; break } }
if !found { return fmt.Errorf("balancer %q not registered", balancer) }

When it happens

Trigger: Calling OverrideBalancer(balancer, target) with a name that is not any balancingRule tag; empty balancer string.

Common situations: 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.

Related errors

• balancing strategy returns empty tag
• unable to select outbounds
• unsupported GetPrincipleTarget
• cannot find tag
• not a StrategyLeastLoadConfig

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