{"record":{"id":"d8d5658adfb9c19c","repo":"run-llama/llama_index","slug":"ref-doc-id-of-node-cannot-be-none-when-building-a","errorCode":null,"errorMessage":"ref_doc_id of node cannot be None when building a document summary index","messagePattern":"ref_doc_id of node cannot be None when building a document summary index","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/data_structs/document_summary.py","lineNumber":35,"sourceCode":"\n    \"\"\"\n\n    summary_id_to_node_ids: Dict[str, List[str]] = field(default_factory=dict)\n    node_id_to_summary_id: Dict[str, str] = field(default_factory=dict)\n\n    # track mapping from doc id to node summary id\n    doc_id_to_summary_id: Dict[str, str] = field(default_factory=dict)\n\n    def add_summary_and_nodes(\n        self,\n        summary_node: BaseNode,\n        nodes: List[BaseNode],\n    ) -> str:\n        \"\"\"Add node and summary.\"\"\"\n        summary_id = summary_node.node_id\n        ref_doc_id = summary_node.ref_doc_id\n        if ref_doc_id is None:\n            raise ValueError(\n                \"ref_doc_id of node cannot be None when building a document \"\n                \"summary index\"\n            )\n        self.doc_id_to_summary_id[ref_doc_id] = summary_id\n\n        for node in nodes:\n            node_id = node.node_id\n            if summary_id not in self.summary_id_to_node_ids:\n                self.summary_id_to_node_ids[summary_id] = []\n            self.summary_id_to_node_ids[summary_id].append(node_id)\n\n            self.node_id_to_summary_id[node_id] = summary_id\n\n        return summary_id\n\n    @property\n    def summary_ids(self) -> List[str]:\n        \"\"\"Get summary ids.\"\"\"","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/data_structs/document_summary.py#L17-L53","documentation":"A DocumentSummaryIndex groups nodes under per-document summary nodes, keyed by the summary node's ref_doc_id (the id of the source Document). add_summary_and_nodes() rejects a summary node with ref_doc_id=None because there would be no document key to register the summary under, silently breaking retrieval.","triggerScenarios":"Building a DocumentSummaryIndex from nodes you created manually (TextNode(...) has no ref_doc_id) instead of nodes produced by a splitter from Documents; or passing summary nodes whose ref_doc_id was stripped (e.g. after node transformations or copying nodes).","commonSituations":"Reusing an existing node list (from another index or an ingestion cache) as input to DocumentSummaryIndex; inserting manually-written summary TextNodes; transformations that clear ref_doc_id.","solutions":["Feed Documents to the index and let it split: DocumentSummaryIndex.from_documents(docs) — splitter sets ref_doc_id on every node","If you must pass nodes, set node.ref_doc_id = doc_id on each (especially the summary) node before building","Check for None first and route offending nodes through a Document wrapper: insert them into Document(text=..., id_=known_id) then split"],"exampleFix":"// before\nnodes = [TextNode(text=\"some content\")]  # ref_doc_id is None\nindex = DocumentSummaryIndex(nodes=nodes)  # ValueError\n\n// after\nfrom llama_index.core import Document\nfrom llama_index.core.node_parser import SentenceSplitter\nnodes = SentenceSplitter().get_nodes_from_documents(\n    [Document(text=\"some content\", id_=\"doc_1\")]\n)  # ref_doc_id set automatically\nindex = DocumentSummaryIndex(nodes=nodes)","handlingStrategy":"validation","validationCode":"missing = [n.id_ for n in nodes if n.ref_doc_id is None]\nif missing:\n    raise ValueError(f\"nodes without ref_doc_id: {missing}\")","typeGuard":"def nodes_have_ref_doc_id(nodes) -> bool:\n    return all(n.ref_doc_id is not None for n in nodes)","tryCatchPattern":null,"preventionTips":["Generate nodes via SentenceSplitter.get_nodes_from_documents, not manual TextNode creation","After node transformations, re-check ref_doc_id before building DocumentSummaryIndex","Wrap Documents with stable id_=... so ref_doc_id is meaningful and reproducible"],"tags":["index","document-summary-index","nodes","data-model"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}