run-llama/llama_index · error · ValueError

ref_doc_id {ref_doc_id} not found.

Error message

ref_doc_id {ref_doc_id} not found.

What it means

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.

Source

Thrown at llama-index-core/llama_index/core/storage/docstore/keyval_docstore.py:562

            raise ValueError(f"doc_id {doc_id} not found.")

    async def adelete_document(self, doc_id: str, raise_error: bool = True) -> None:
        """Delete a document from the store."""
        _, delete_success, _ = await asyncio.gather(
            self._aremove_from_ref_doc_node(doc_id),
            self._kvstore.adelete(doc_id, collection=self._node_collection),
            self._kvstore.adelete(doc_id, collection=self._metadata_collection),
        )

        if not delete_success and raise_error:
            raise ValueError(f"doc_id {doc_id} not found.")

    def delete_ref_doc(self, ref_doc_id: str, raise_error: bool = True) -> None:
        """Delete a ref_doc and all it's associated nodes."""
        ref_doc_info = self.get_ref_doc_info(ref_doc_id)
        if ref_doc_info is None:
            if raise_error:
                raise ValueError(f"ref_doc_id {ref_doc_id} not found.")
            else:
                return

        original_node_ids = (
            ref_doc_info.node_ids.copy()
        )  # copy to avoid mutation during iteration
        for doc_id in original_node_ids:
            self.delete_document(doc_id, raise_error=False)

        # Deleting all the nodes should already delete the ref_doc, but just to be sure
        self._kvstore.delete(ref_doc_id, collection=self._ref_doc_collection)
        self._kvstore.delete(ref_doc_id, collection=self._metadata_collection)
        self._kvstore.delete(ref_doc_id, collection=self._node_collection)

    async def adelete_ref_doc(self, ref_doc_id: str, raise_error: bool = True) -> None:
        """Delete a ref_doc and all it's associated nodes."""
        ref_doc_info = await self.aget_ref_doc_info(ref_doc_id)
        if ref_doc_info is None:

View on GitHub (pinned to afd0fef371)

Solutions

1. Pass raise_error=False when double-delete is expected: docstore.delete_ref_doc(ref_doc_id, raise_error=False).
2. Check existence first: docstore.get_ref_doc_info(ref_doc_id) is not None.
3. Make sure you pass the source document's ID (doc_id of the ingested Document), not a child node_id.
4. For full pipeline removal, use the index/document-management API (e.g. index.delete_ref_doc) which coordinates docstore+vector store.

Example fix

# before
docstore.delete_ref_doc(doc_id)  # raises if already deleted

# after
if docstore.get_ref_doc_info(doc_id) is not None:
    docstore.delete_ref_doc(doc_id)

def delete_ref_doc_idempotent(docstore, ref_doc_id) -> bool:
    if docstore.get_ref_doc_info(ref_doc_id) is None:
        return False
    docstore.delete_ref_doc(ref_doc_id)
    return True

def ref_doc_exists(docstore, ref_doc_id: str) -> bool:
    return docstore.get_ref_doc_info(ref_doc_id) is not None

try:
    docstore.delete_ref_doc(ref_doc_id)
except ValueError as e:
    if 'not found' in str(e):
        pass  # already gone
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• doc_id {doc_id} not found.
• Node {node_id} not found
• First argument to Readability constructor should be a docume
• Aborting parsing document; {numTags} elements found
• Command failed: {command} {result.stderr}

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