OpenNHP/opennhp · error

unknown load-balance scheme

Error message

unknown load-balance scheme %q (valid: %q, %q, %q)

What it means

Raised by loadbalance.Scheme.Validate when the configured scheme string is non-empty but matches none of the registered schemes (random, weighted-random, round-robin). It is a config-load-time typo catcher: empty strings are accepted and later normalized to DefaultScheme, so this error specifically means a misspelled or unknown scheme value was supplied.

Solutions

1. Correct the scheme to one of the values enumerated in the error message
2. Leave the field empty/unset to accept the default (weighted-random)
3. Check for version skew if a scheme name valid in another release was used

When it happens

Trigger: Thrown at nhp/common/loadbalance/loadbalance.go:43 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of OpenNHP/opennhp@6e04ca5ff0 (2026-09-07). Data as JSON: /api/errors/c86406fc0139fd14. Report an issue: GitHub.

Appendix: source

Thrown at nhp/common/loadbalance/loadbalance.go:43

	SchemeWeightedRandom Scheme = "weighted-random"
	SchemeRoundRobin     Scheme = "round-robin"
)

// DefaultScheme is what an empty / unset scheme normalises to.
// Weighted-random matches the documented intuition "spread requests
// proportionally to declared instance weights" without surprising
// operators who left the field blank.
const DefaultScheme = SchemeWeightedRandom

// Validate rejects unknown scheme strings at config-load time. An empty
// string is accepted; callers should normalise it to DefaultScheme via
// Normalize before constructing a Picker.
func (s Scheme) Validate() error {
	switch s {
	case "", SchemeRandom, SchemeWeightedRandom, SchemeRoundRobin:
		return nil
	default:
		return fmt.Errorf("unknown load-balance scheme %q (valid: %q, %q, %q)",
			string(s), SchemeRandom, SchemeWeightedRandom, SchemeRoundRobin)
	}
}

// Normalize returns the scheme with the empty string replaced by
// DefaultScheme. Unknown schemes pass through unchanged — call
// Validate first to reject them.
func (s Scheme) Normalize() Scheme {
	if s == "" {
		return DefaultScheme
	}
	return s
}

// Weighted is the contract an instance type must satisfy to be Picked.
// Implementations should return a non-negative integer; zero weight is
// treated as 1 in NormalizeWeights so an instance with weight 0 in the
// config still receives traffic.

View on GitHub (pinned to 6e04ca5ff0)