run-llama/llama_index · error · ValueError

doc_id {doc_id} not in index

Error message

doc_id {doc_id} not in index

What it means

DocumentSummaryIndex.get_document_summary maps a document id to its summary node via index_struct.doc_id_to_summary_id. If the doc_id is not a key in that mapping (never inserted, different id scheme, or index rebuilt), it raises ValueError(f"doc_id {doc_id} not in index").

Source

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

                **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],
        show_progress: bool = False,
    ) -> None:
        """Add nodes to index."""
        doc_id_to_nodes = defaultdict(list)
        for node in nodes:
            if node.ref_doc_id is None:
                raise ValueError(
                    "ref_doc_id of node cannot be None when building a document "
                    "summary index"
                )
            doc_id_to_nodes[node.ref_doc_id].append(node)

View on GitHub (pinned to afd0fef371)

Solutions

1. Check membership first: if doc_id in index.index_struct.doc_id_to_summary_id before calling.
2. List valid ids via index.index_struct.doc_id_to_summary_id.keys() and compare against the id you hold.
3. Ensure you use the same id that the documents were indexed under (Document.id_ / ref_doc_id of their nodes), and rebuild the index if the corpus changed.

Example fix

# before
summary = index.get_document_summary("doc-42")  # ValueError if absent

# after
summary = (
    index.get_document_summary("doc-42")
    if "doc-42" in index.index_struct.doc_id_to_summary_id
    else "(no summary for this document)"
)

if doc_id not in index.index_struct.doc_id_to_summary_id:
    available = list(index.index_struct.doc_id_to_summary_id)[:10]
    raise KeyError(f"{doc_id} not indexed; sample ids: {available}")

def doc_has_summary(index, doc_id: str) -> bool:
    return doc_id in index.index_struct.doc_id_to_summary_id

try:
    summary = index.get_document_summary(doc_id)
except ValueError:
    summary = None  # handle unknown document gracefully in the UI

When it happens

Trigger: Calling get_document_summary('some_id') with an id that was never indexed; using source Document.id_ vs the node's ref_doc_id inconsistently after transforms; querying an index loaded from storage that was built from a different corpus.

Common situations: Frontends persisting document ids from one index build and replaying them against a rebuilt index; inserts via index.insert() of Documents whose id_ differs from the ref_doc_id the summary index keys on; debugging hooks enumerating ids from the wrong collection.

Related errors

• Cannot use embedding retriever if embed_summaries is False
• Unknown retriever mode: {retriever_mode}
• ref_doc_id of node cannot be None when building a document s
• Max iterations of {max_iterations} reached! Either something
• All agents must have a name in a multi-agent workflow

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