{"record":{"id":"890e3542d5d85792","repo":"run-llama/llama_index","slug":"unknown-retriever-mode-retriever-mode-890e35","errorCode":null,"errorMessage":"Unknown retriever mode: {retriever_mode}","messagePattern":"Unknown retriever mode: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/indices/tree/base.py","lineNumber":128,"sourceCode":"        from llama_index.core.indices.tree.tree_root_retriever import (\n            TreeRootRetriever,\n        )\n\n        self._validate_build_tree_required(TreeRetrieverMode(retriever_mode))\n\n        if retriever_mode == TreeRetrieverMode.SELECT_LEAF:\n            return TreeSelectLeafRetriever(self, object_map=self._object_map, **kwargs)\n        elif retriever_mode == TreeRetrieverMode.SELECT_LEAF_EMBEDDING:\n            embed_model = embed_model or Settings.embed_model\n            return TreeSelectLeafEmbeddingRetriever(\n                self, embed_model=embed_model, object_map=self._object_map, **kwargs\n            )\n        elif retriever_mode == TreeRetrieverMode.ROOT:\n            return TreeRootRetriever(self, object_map=self._object_map, **kwargs)\n        elif retriever_mode == TreeRetrieverMode.ALL_LEAF:\n            return TreeAllLeafRetriever(self, object_map=self._object_map, **kwargs)\n        else:\n            raise ValueError(f\"Unknown retriever mode: {retriever_mode}\")\n\n    def _validate_build_tree_required(self, retriever_mode: TreeRetrieverMode) -> None:\n        \"\"\"Check if index supports modes that require trees.\"\"\"\n        if retriever_mode in REQUIRE_TREE_MODES and not self.build_tree:\n            raise ValueError(\n                \"Index was constructed without building trees, \"\n                f\"but retriever mode {retriever_mode} requires trees.\"\n            )\n\n    def _build_index_from_nodes(\n        self, nodes: Sequence[BaseNode], **build_kwargs: Any\n    ) -> IndexGraph:\n        \"\"\"Build the index from nodes.\"\"\"\n        index_builder = GPTTreeIndexBuilder(\n            self.num_children,\n            self.summary_template,\n            llm=self._llm,\n            use_async=self._use_async,","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/indices/tree/base.py#L110-L146","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use the enum: from llama_index.core.indices.tree.base import TreeRetrieverMode; index.as_retriever(retriever_mode=TreeRetrieverMode.ALL_LEAF).","If using strings, use exactly 'select_leaf', 'select_leaf_embedding', 'root', or 'all_leaf'.","Omit retriever_mode — the default is SELECT_LEAF."],"exampleFix":"# before\nretriever = tree_index.as_retriever(retriever_mode=\"leaf\")  # ValueError\n\n# after\nfrom llama_index.core.indices.tree.base import TreeRetrieverMode\nretriever = tree_index.as_retriever(retriever_mode=TreeRetrieverMode.ALL_LEAF)","handlingStrategy":"type-guard","validationCode":"from llama_index.core.indices.tree.base import TreeRetrieverMode\n\nVALID_TREE_MODES = {m.value for m in TreeRetrieverMode}\n\ndef resolve_tree_mode(m) -> TreeRetrieverMode:\n    mode = TreeRetrieverMode(m) if isinstance(m, str) else m\n    if mode.value not in VALID_TREE_MODES:\n        raise ValueError(f\"unknown tree retriever mode {m}; valid: {VALID_TREE_MODES}\")\n    return mode","typeGuard":"from llama_index.core.indices.tree.base import TreeRetrieverMode\n\ndef is_valid_tree_mode(m) -> bool:\n    try:\n        return TreeRetrieverMode(m) in list(TreeRetrieverMode)\n    except ValueError:\n        return False","tryCatchPattern":null,"preventionTips":["Always use TreeRetrieverMode enum members (SELECT_LEAF, SELECT_LEAF_EMBEDDING, ROOT, ALL_LEAF).","Validate user/config-supplied mode strings with TreeRetrieverMode(value) before passing them on.","Re-check mode names after major llama-index version upgrades."],"tags":["tree-index","enum","retriever","llama-index"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}