{"record":{"id":"974e810f2632c114","repo":"run-llama/llama_index","slug":"ref-doc-id-ref-doc-id-not-found","errorCode":null,"errorMessage":"ref_doc_id {ref_doc_id} not found.","messagePattern":"ref_doc_id (.+?) not found\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/storage/docstore/keyval_docstore.py","lineNumber":562,"sourceCode":"            raise ValueError(f\"doc_id {doc_id} not found.\")\n\n    async def adelete_document(self, doc_id: str, raise_error: bool = True) -> None:\n        \"\"\"Delete a document from the store.\"\"\"\n        _, delete_success, _ = await asyncio.gather(\n            self._aremove_from_ref_doc_node(doc_id),\n            self._kvstore.adelete(doc_id, collection=self._node_collection),\n            self._kvstore.adelete(doc_id, collection=self._metadata_collection),\n        )\n\n        if not delete_success and raise_error:\n            raise ValueError(f\"doc_id {doc_id} not found.\")\n\n    def delete_ref_doc(self, ref_doc_id: str, raise_error: bool = True) -> None:\n        \"\"\"Delete a ref_doc and all it's associated nodes.\"\"\"\n        ref_doc_info = self.get_ref_doc_info(ref_doc_id)\n        if ref_doc_info is None:\n            if raise_error:\n                raise ValueError(f\"ref_doc_id {ref_doc_id} not found.\")\n            else:\n                return\n\n        original_node_ids = (\n            ref_doc_info.node_ids.copy()\n        )  # copy to avoid mutation during iteration\n        for doc_id in original_node_ids:\n            self.delete_document(doc_id, raise_error=False)\n\n        # Deleting all the nodes should already delete the ref_doc, but just to be sure\n        self._kvstore.delete(ref_doc_id, collection=self._ref_doc_collection)\n        self._kvstore.delete(ref_doc_id, collection=self._metadata_collection)\n        self._kvstore.delete(ref_doc_id, collection=self._node_collection)\n\n    async def adelete_ref_doc(self, ref_doc_id: str, raise_error: bool = True) -> None:\n        \"\"\"Delete a ref_doc and all it's associated nodes.\"\"\"\n        ref_doc_info = await self.aget_ref_doc_info(ref_doc_id)\n        if ref_doc_info is None:","sourceCodeStart":544,"sourceCodeEnd":580,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/storage/docstore/keyval_docstore.py#L544-L580","documentation":"KeyValDocumentStore.delete_ref_doc(ref_doc_id, raise_error=True) first fetches ref_doc_info from the ref-doc collection; if that returns None (no source document registered under ref_doc_id), it raises. With raise_error=False it silently returns. On success it cascades deletion of all child nodes.","triggerScenarios":"docstore.delete_ref_doc(ref_doc_id) for a source-document ID never stored or already removed; using a node_id instead of the source doc's ID; calling after the node cascade already removed the ref-doc entry.","commonSituations":"Document-removal flows in RAG apps (delete source doc and its chunks); re-sync jobs deleting outdated docs; inconsistent state after a partially failed earlier deletion.","solutions":["Pass raise_error=False when double-delete is expected: docstore.delete_ref_doc(ref_doc_id, raise_error=False).","Check existence first: docstore.get_ref_doc_info(ref_doc_id) is not None.","Make sure you pass the source document's ID (doc_id of the ingested Document), not a child node_id.","For full pipeline removal, use the index/document-management API (e.g. index.delete_ref_doc) which coordinates docstore+vector store."],"exampleFix":"# before\ndocstore.delete_ref_doc(doc_id)  # raises if already deleted\n\n# after\nif docstore.get_ref_doc_info(doc_id) is not None:\n    docstore.delete_ref_doc(doc_id)","handlingStrategy":"validation","validationCode":"def delete_ref_doc_idempotent(docstore, ref_doc_id) -> bool:\n    if docstore.get_ref_doc_info(ref_doc_id) is None:\n        return False\n    docstore.delete_ref_doc(ref_doc_id)\n    return True","typeGuard":"def ref_doc_exists(docstore, ref_doc_id: str) -> bool:\n    return docstore.get_ref_doc_info(ref_doc_id) is not None","tryCatchPattern":"try:\n    docstore.delete_ref_doc(ref_doc_id)\nexcept ValueError as e:\n    if 'not found' in str(e):\n        pass  # already gone\n    else:\n        raise","preventionTips":["Delete by the source Document's ID, never a child node_id, when using delete_ref_doc.","Treat repeated deletes as no-ops with raise_error=False.","Use index-level document management so docstore and vector store stay in sync."],"tags":["docstore","delete","ref-doc","not-found","llama-index"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}