{"record":{"id":"8d9a67ca726c01bc","repo":"run-llama/llama_index","slug":"unknown-retriever-mode-retriever-mode-8d9a67","errorCode":null,"errorMessage":"Unknown retriever mode: {retriever_mode}","messagePattern":"Unknown retriever mode: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/indices/list/base.py","lineNumber":94,"sourceCode":"            SummaryIndexEmbeddingRetriever,\n            SummaryIndexLLMRetriever,\n            SummaryIndexRetriever,\n        )\n\n        if retriever_mode == ListRetrieverMode.DEFAULT:\n            return SummaryIndexRetriever(self, object_map=self._object_map, **kwargs)\n        elif retriever_mode == ListRetrieverMode.EMBEDDING:\n            embed_model = embed_model or Settings.embed_model\n            return SummaryIndexEmbeddingRetriever(\n                self, object_map=self._object_map, embed_model=embed_model, **kwargs\n            )\n        elif retriever_mode == ListRetrieverMode.LLM:\n            llm = llm or Settings.llm\n            return SummaryIndexLLMRetriever(\n                self, object_map=self._object_map, llm=llm, **kwargs\n            )\n        else:\n            raise ValueError(f\"Unknown retriever mode: {retriever_mode}\")\n\n    def _build_index_from_nodes(\n        self,\n        nodes: Sequence[BaseNode],\n        show_progress: bool = False,\n        **build_kwargs: Any,\n    ) -> IndexList:\n        \"\"\"\n        Build the index from documents.\n\n        Args:\n            documents (List[BaseDocument]): A list of documents.\n\n        Returns:\n            IndexList: The created summary index.\n\n        \"\"\"\n        index_struct = IndexList()","sourceCodeStart":76,"sourceCodeEnd":112,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/indices/list/base.py#L76-L112","documentation":"SummaryIndex (formerly ListIndex, file indices/list/base.py) as_retriever() accepts only ListRetrieverMode.DEFAULT, EMBEDDING, and LLM. Any other mode string falls through to a ValueError. Each valid mode selects a different retriever class (SummaryIndexRetriever, SummaryIndexEmbeddingRetriever with Settings.embed_model, or SummaryIndexLLMRetriever with Settings.llm).","triggerScenarios":"summary_index.as_retriever(retriever_mode='rake'), 'keyword', or any VectorStoreIndex/KeywordTable mode name; passing a typo or a config value from a different index family; calling as_query_engine(..., retriever_mode=...) which forwards the kwarg to as_retriever.","commonSituations":"Shared config-driven retriever factory applying one mode string across index types; renaming between llama-index versions (ListIndex -> SummaryIndex changed enum naming); copy-pasted examples mixing index kinds.","solutions":["Use a valid mode: ListRetrieverMode.DEFAULT ('default'), EMBEDDING ('embedding'), or LLM ('llm').","Import the enum instead of hardcoding strings: from llama_index.core.indices.list import ListRetrieverMode.","For keyword/table retrieval, switch to KeywordTableIndex rather than forcing an unsupported mode on SummaryIndex."],"exampleFix":"# before\nretriever = summary_index.as_retriever(retriever_mode=\"compact\")\n\n# after\nfrom llama_index.core.indices.list import ListRetrieverMode\nretriever = summary_index.as_retriever(retriever_mode=ListRetrieverMode.EMBEDDING)","handlingStrategy":"validation","validationCode":"from llama_index.core.indices.list import ListRetrieverMode\n\nVALID = set(ListRetrieverMode)\nassert mode in VALID, f\"mode must be one of {VALID}\"\nretriever = summary_index.as_retriever(retriever_mode=mode)","typeGuard":null,"tryCatchPattern":"try:\n    retriever = summary_index.as_retriever(retriever_mode=mode)\nexcept ValueError as e:\n    if \"Unknown retriever mode\" in str(e):\n        retriever = summary_index.as_retriever()  # default mode\n    else:\n        raise","preventionTips":["Use ListRetrieverMode enum members instead of string literals.","Validate mode config once at startup against the enum for the index type in use.","Remember ListIndex is now SummaryIndex — update stale mode strings when upgrading."],"tags":["llama-index","summary-index","retriever","configuration","validation"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}