XTLS/Xray-core · error

unrecognized balancer type

Error message

unrecognized balancer type

What it means

BalancingRule.Build switches on the lowercased strategy name and only accepts leastping, leastload, random, and empty string. Any other value falls to default and fails balancer construction, which in turn fails router startup or ReloadRules.

Source

Thrown at app/router/config.go:167

		}
		leastLoadStrategy := NewLeastLoadStrategy(s)
		return &Balancer{
			selectors:   br.OutboundSelector,
			ohm:         ohm,
			fallbackTag: br.FallbackTag,
			strategy:    leastLoadStrategy,
		}, nil
	case "random":
		fallthrough
	case "":
		return &Balancer{
			selectors:   br.OutboundSelector,
			ohm:         ohm,
			fallbackTag: br.FallbackTag,
			strategy:    &RandomStrategy{FallbackTag: br.FallbackTag},
		}, nil
	default:
		return nil, errors.New("unrecognized balancer type")
	}
}

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Use one of: leastping, leastload, random, or omit strategy for the default random behavior
2. Check for stray whitespace/case in the strategy value
3. Consult the current config docs for the supported strategy list of your version

Example fix

// before
"strategy": { "type": "round-robin" }

// after
"strategy": { "type": "random" }

var validStrategies = map[string]bool{"leastping": true, "leastload": true, "random": true, "": true}
if !validStrategies[strings.ToLower(strings.TrimSpace(strategy))] {
    return fmt.Errorf("unsupported strategy %q; use leastping|leastload|random", strategy)
}

When it happens

Trigger: Setting strategy.type to an unknown string (e.g. 'roundrobin' spelled out, 'leastPing' with odd casing is fine due to ToLower, but 'minping' or a typo like 'leastLoad ' with trailing space in some paths) — any value outside the accepted set.

Common situations: Typos in hand-written configs; strategies renamed or removed across versions; copying configs from other projects with custom strategy extensions.

Related errors

• not a StrategyLeastLoadConfig
• balancer %s not found
• 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/e8dc10443620126c. Report an issue: GitHub.