run-llama/llama_index · error · ValueError

Cannot use embedding retriever if embed_summaries is False

Error message

Cannot use embedding retriever if embed_summaries is False

What it means

DocumentSummaryIndexEmbeddingRetriever ranks documents by embedding similarity over their summary nodes. Those summary embeddings only exist when the index was built with embed_summaries=True; with the default False, no embeddings were computed and stored, so requesting the EMBEDDING retriever mode raises ValueError at retriever construction time.

Source

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

        """
        Get retriever.

        Args:
            retriever_mode (Union[str, DocumentSummaryRetrieverMode]): A retriever mode.
                Defaults to DocumentSummaryRetrieverMode.EMBEDDING.

        """
        from llama_index.core.indices.document_summary.retrievers import (
            DocumentSummaryIndexEmbeddingRetriever,
            DocumentSummaryIndexLLMRetriever,
        )

        LLMRetriever = DocumentSummaryIndexLLMRetriever
        EmbeddingRetriever = DocumentSummaryIndexEmbeddingRetriever

        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:
        """

View on GitHub (pinned to afd0fef371)

Solutions

1. Rebuild the index with embed_summaries=True: DocumentSummaryIndex.from_documents(docs, embed_summaries=True).
2. Or keep the default index and use retriever_mode='llm' (DocumentSummaryIndexLLMRetriever), which needs no embeddings.
3. If using 'default' mode, note it routes to LLM retriever unless embeddings were built — set the mode explicitly.

Example fix

# before
index = DocumentSummaryIndex.from_documents(docs)  # embed_summaries=False
retriever = index.as_retriever(retriever_mode="embedding")  # ValueError

# after
index = DocumentSummaryIndex.from_documents(docs, embed_summaries=True)
retriever = index.as_retriever(retriever_mode="embedding")

if retriever_mode in ("embedding",) and not index._embed_summaries:
    raise ValueError("Rebuild index with embed_summaries=True or use mode 'llm'")

When it happens

Trigger: DocumentSummaryIndex(..., embed_summaries=False).as_retriever(retriever_mode='embedding'); using the string or enum _RetrieverMode.EMBEDDING / DEFAULT-with-embedding paths on a default-constructed DocumentSummaryIndex.

Common situations: Following a retrieval-mode example without setting embed_summaries; switching a working LLM-mode setup to embedding mode after index construction; cost-conscious defaults (embed_summaries defaults to False) surprising users later.

Related errors

• Unknown retriever mode: {retriever_mode}
• Must specify both response and reference
• doc_id {doc_id} not in index
• ref_doc_id of node cannot be None when building a document s
• Vector store query result should return at least one of node

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