run-llama/llama_index · error · ValueError

Unknown retriever mode: {retriever_mode}

Error message

Unknown retriever mode: {retriever_mode}

What it means

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).

Source

Thrown at llama-index-core/llama_index/core/indices/list/base.py:94

            SummaryIndexEmbeddingRetriever,
            SummaryIndexLLMRetriever,
            SummaryIndexRetriever,
        )

        if retriever_mode == ListRetrieverMode.DEFAULT:
            return SummaryIndexRetriever(self, object_map=self._object_map, **kwargs)
        elif retriever_mode == ListRetrieverMode.EMBEDDING:
            embed_model = embed_model or Settings.embed_model
            return SummaryIndexEmbeddingRetriever(
                self, object_map=self._object_map, embed_model=embed_model, **kwargs
            )
        elif retriever_mode == ListRetrieverMode.LLM:
            llm = llm or Settings.llm
            return SummaryIndexLLMRetriever(
                self, object_map=self._object_map, llm=llm, **kwargs
            )
        else:
            raise ValueError(f"Unknown retriever mode: {retriever_mode}")

    def _build_index_from_nodes(
        self,
        nodes: Sequence[BaseNode],
        show_progress: bool = False,
        **build_kwargs: Any,
    ) -> IndexList:
        """
        Build the index from documents.

        Args:
            documents (List[BaseDocument]): A list of documents.

        Returns:
            IndexList: The created summary index.

        """
        index_struct = IndexList()

View on GitHub (pinned to afd0fef371)

Solutions

1. Use a valid mode: ListRetrieverMode.DEFAULT ('default'), EMBEDDING ('embedding'), or LLM ('llm').
2. Import the enum instead of hardcoding strings: from llama_index.core.indices.list import ListRetrieverMode.
3. For keyword/table retrieval, switch to KeywordTableIndex rather than forcing an unsupported mode on SummaryIndex.

Example fix

# before
retriever = summary_index.as_retriever(retriever_mode="compact")

# after
from llama_index.core.indices.list import ListRetrieverMode
retriever = summary_index.as_retriever(retriever_mode=ListRetrieverMode.EMBEDDING)

from llama_index.core.indices.list import ListRetrieverMode

VALID = set(ListRetrieverMode)
assert mode in VALID, f"mode must be one of {VALID}"
retriever = summary_index.as_retriever(retriever_mode=mode)

try:
    retriever = summary_index.as_retriever(retriever_mode=mode)
except ValueError as e:
    if "Unknown retriever mode" in str(e):
        retriever = summary_index.as_retriever()  # default mode
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unknown retriever mode: {retriever_mode}
• Cannot initialize from a vector store that does not store te
• llm must start with str 'local' or of type LLM or BaseLangua
• Token limit must be set and greater than 0.
• Token limit for full-text messages must be set and greater t

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