run-llama/llama_index · error · ValueError

Unknown retriever mode: {retriever_mode}

Error message

Unknown retriever mode: {retriever_mode}

What it means

DocumentSummaryIndex.as_retriever dispatches on retriever_mode (LLM, EMBEDDING, DEFAULT) and raises ValueError(f"Unknown retriever mode: {retriever_mode}") for any other value. The mode must be a _RetrieverMode enum member or one of the equivalent strings.

Source

Thrown at llama-index-core/llama_index/core/indices/document_summary/base.py:150

        if retriever_mode == _RetrieverMode.EMBEDDING:
            if not self._embed_summaries:
                raise ValueError(
                    "Cannot use embedding retriever if embed_summaries is False"
                )

            return EmbeddingRetriever(
                self,
                object_map=self._object_map,
                embed_model=self._embed_model,
                **kwargs,
            )
        if retriever_mode == _RetrieverMode.LLM:
            return LLMRetriever(
                self, object_map=self._object_map, llm=self._llm, **kwargs
            )
        else:
            raise ValueError(f"Unknown retriever mode: {retriever_mode}")

    def get_document_summary(self, doc_id: str) -> str:
        """
        Get document summary by doc id.

        Args:
            doc_id (str): A document id.

        """
        if doc_id not in self._index_struct.doc_id_to_summary_id:
            raise ValueError(f"doc_id {doc_id} not in index")
        summary_id = self._index_struct.doc_id_to_summary_id[doc_id]
        return self.docstore.get_node(summary_id).get_content()

    def _add_nodes_to_index(
        self,
        index_struct: IndexDocumentSummary,
        nodes: Sequence[BaseNode],

View on GitHub (pinned to afd0fef371)

Solutions

1. Use exactly 'llm', 'embedding', or 'default' (or the corresponding DocumentSummaryIndex/_RetrieverMode enum members).
2. Inspect the accepted modes: from llama_index.core.indices.document_summary.base import _RetrieverMode; print(list(_RetrieverMode)).
3. Omit retriever_mode to get the DEFAULT mode.

Example fix

# before
retriever = index.as_retriever(retriever_mode="embed")  # Unknown retriever mode

# after
retriever = index.as_retriever(retriever_mode="embedding")  # requires embed_summaries=True
# or
retriever = index.as_retriever(retriever_mode="llm")

valid_modes = {"default", "llm", "embedding"}
if retriever_mode not in valid_modes:
    raise ValueError(f"retriever_mode must be one of {sorted(valid_modes)}")

def is_valid_retriever_mode(mode) -> bool:
    return mode in {"default", "llm", "embedding"}

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

When it happens

Trigger: Passing a typo like retriever_mode='embed' or 'vector' instead of 'embedding'; passing a mode constant from a different index class's enum; passing None explicitly instead of omitting the argument.

Common situations: Copy/paste from VectorIndexRetriever examples where the mode vocabulary differs; hallucinated mode names; version drift if mode strings changed.

Related errors

• Cannot use embedding retriever if embed_summaries is False
• Unsupported mode.
• Unknown chat mode: {chat_mode}
• doc_id {doc_id} not in index
• ref_doc_id of node cannot be None when building a document s

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