run-llama/llama_index · error · ValueError

Unknown retriever mode: {retriever_mode}

Error message

Unknown retriever mode: {retriever_mode}

What it means

TreeIndex.as_retriever raises ValueError(f'Unknown retriever mode: {retriever_mode}') when the mode is not one of select_leaf, select_leaf_embedding, root, or all_leaf (TreeRetrieverMode members). The if/elif chain compares against enum members whose string values are lowercase, so any other string, a misspelled mode, or a mode from a different enum falls to the else. This fails at retriever construction time, before any query runs.

Source

Thrown at llama-index-core/llama_index/core/indices/tree/base.py:128

        from llama_index.core.indices.tree.tree_root_retriever import (
            TreeRootRetriever,
        )

        self._validate_build_tree_required(TreeRetrieverMode(retriever_mode))

        if retriever_mode == TreeRetrieverMode.SELECT_LEAF:
            return TreeSelectLeafRetriever(self, object_map=self._object_map, **kwargs)
        elif retriever_mode == TreeRetrieverMode.SELECT_LEAF_EMBEDDING:
            embed_model = embed_model or Settings.embed_model
            return TreeSelectLeafEmbeddingRetriever(
                self, embed_model=embed_model, object_map=self._object_map, **kwargs
            )
        elif retriever_mode == TreeRetrieverMode.ROOT:
            return TreeRootRetriever(self, object_map=self._object_map, **kwargs)
        elif retriever_mode == TreeRetrieverMode.ALL_LEAF:
            return TreeAllLeafRetriever(self, object_map=self._object_map, **kwargs)
        else:
            raise ValueError(f"Unknown retriever mode: {retriever_mode}")

    def _validate_build_tree_required(self, retriever_mode: TreeRetrieverMode) -> None:
        """Check if index supports modes that require trees."""
        if retriever_mode in REQUIRE_TREE_MODES and not self.build_tree:
            raise ValueError(
                "Index was constructed without building trees, "
                f"but retriever mode {retriever_mode} requires trees."
            )

    def _build_index_from_nodes(
        self, nodes: Sequence[BaseNode], **build_kwargs: Any
    ) -> IndexGraph:
        """Build the index from nodes."""
        index_builder = GPTTreeIndexBuilder(
            self.num_children,
            self.summary_template,
            llm=self._llm,
            use_async=self._use_async,

View on GitHub (pinned to afd0fef371)

Solutions

1. Use the enum: from llama_index.core.indices.tree.base import TreeRetrieverMode; index.as_retriever(retriever_mode=TreeRetrieverMode.ALL_LEAF).
2. If using strings, use exactly 'select_leaf', 'select_leaf_embedding', 'root', or 'all_leaf'.
3. Omit retriever_mode — the default is SELECT_LEAF.

Example fix

# before
retriever = tree_index.as_retriever(retriever_mode="leaf")  # ValueError

# after
from llama_index.core.indices.tree.base import TreeRetrieverMode
retriever = tree_index.as_retriever(retriever_mode=TreeRetrieverMode.ALL_LEAF)

from llama_index.core.indices.tree.base import TreeRetrieverMode

VALID_TREE_MODES = {m.value for m in TreeRetrieverMode}

def resolve_tree_mode(m) -> TreeRetrieverMode:
    mode = TreeRetrieverMode(m) if isinstance(m, str) else m
    if mode.value not in VALID_TREE_MODES:
        raise ValueError(f"unknown tree retriever mode {m}; valid: {VALID_TREE_MODES}")
    return mode

from llama_index.core.indices.tree.base import TreeRetrieverMode

def is_valid_tree_mode(m) -> bool:
    try:
        return TreeRetrieverMode(m) in list(TreeRetrieverMode)
    except ValueError:
        return False

When it happens

Trigger: TreeIndex(...).as_retriever(retriever_mode='leaf') or 'embedding' (real mode string is 'all_leaf' / 'select_leaf_embedding'); passing TreeSelectLeafEmbeddingRetriever's class name as a string; passing a VectorStore query mode enum by mistake.

Common situations: Guessing mode names from intuition instead of docs; older llama_index (<0.10) examples used different constants/names; mixing up mode strings between tree index and vector index retrievers.

Related errors

• Unknown SQL parser mode: {sql_parser_mode}
• Index was constructed without building trees, but retriever
• LLM must be a FunctionCallingLLM
• Unknown retriever mode: {retriever_mode}
• Unknown retriever mode: {retriever_mode}

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/890e3542d5d85792. Report an issue: GitHub.