livekit/livekit · error

unknown node selector algorithm option

Error message

unknown node selector algorithm option

What it means

ErrAlgorithmUnknown is returned by SelectSortedNode when the Algorithm value matches no known algorithm branch (oneof, twochoice, etc.). Unlike ErrAlgorithmNotSet (empty), this means a non-empty but unrecognized algorithm was supplied.

Source

Thrown at pkg/routing/selector/errors.go:26

//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package selector

import "errors"

var (
	ErrNoAvailableNodes           = errors.New("could not find any available nodes")
	ErrCurrentRegionNotSet        = errors.New("current region cannot be blank")
	ErrCurrentRegionUnknownLatLon = errors.New("unknown lat and lon for the current region")
	ErrSortByNotSet               = errors.New("sort by option cannot be blank")
	ErrAlgorithmNotSet            = errors.New("node selector algorithm option cannot be blank")
	ErrSortByUnknown              = errors.New("unknown sort by option")
	ErrAlgorithmUnknown           = errors.New("unknown node selector algorithm option")
)

View on GitHub (pinned to ee45c3f0b1)

Solutions

1. Verify the algorithm name against the supported set in pkg/routing/selector/utils.go and correct the config.
2. Pin the LiveKit version and check its changelog for algorithm renames.
3. Validate the algorithm at config load time so it fails at startup rather than per-request.

Example fix

// before
algorithm: "least-loaded"
// after
algorithm: "twochoice"

var validAlgorithms = map[string]bool{"oneof": true, "twochoice": true}
if sel.Algorithm != "" && !validAlgorithms[sel.Algorithm] {
  return fmt.Errorf("unsupported node_selector.algorithm: %q", sel.Algorithm)
}

node, err := sel.SelectNode(nodes)
if errors.Is(err, selector.ErrAlgorithmUnknown) {
  logger.Errorw("invalid node selector algorithm", "algorithm", sel.Algorithm)
}

When it happens

Trigger: Calling SelectNode with a selector whose Algorithm is set to a string not handled in the switch at pkg/routing/selector/utils.go:93, such as "leastloaded" or a misspelled "two-chice".

Common situations: Typos in node_selector.algorithm config; documenting/inventing algorithm names not implemented in the deployed LiveKit version; version drift where an algorithm was renamed or removed.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• node selector algorithm option cannot be blank
• unknown sort by option
• unsupported node selector
• key file others permissions must be set to 0
• turn secret file others permissions must be set to 0

AI-assisted analysis of livekit/livekit@ee45c3f0b1 (2026-09-02). Data as JSON: /api/errors/f72417ae67550418. Report an issue: GitHub.