run-llama/llama_index · error · ValueError

doc_id {doc_id} not found.

Error message

doc_id {doc_id} not found.

What it means

KeyValDocumentStore.get_document(doc_id, raise_error=True) raises when the key-value store has no entry for doc_id in the node collection. raise_error defaults to True; pass raise_error=False to get None back instead. The same ID namespace is shared by documents and nodes.

Source

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

                ref_doc_kv_pairs,
                collection=self._ref_doc_collection,
                batch_size=batch_size,
            ),
        )

    def get_document(self, doc_id: str, raise_error: bool = True) -> Optional[BaseNode]:
        """
        Get a document from the store.

        Args:
            doc_id (str): document id
            raise_error (bool): raise error if doc_id not found

        """
        json = self._kvstore.get(doc_id, collection=self._node_collection)
        if json is None:
            if raise_error:
                raise ValueError(f"doc_id {doc_id} not found.")
            else:
                return None
        return json_to_doc(json)

    async def aget_document(
        self, doc_id: str, raise_error: bool = True
    ) -> Optional[BaseNode]:
        """
        Get a document from the store.

        Args:
            doc_id (str): document id
            raise_error (bool): raise error if doc_id not found

        """
        json = await self._kvstore.aget(doc_id, collection=self._node_collection)
        if json is None:
            if raise_error:

View on GitHub (pinned to afd0fef371)

Solutions

1. Pass raise_error=False and handle None if absence is expected: docstore.get_document(doc_id, raise_error=False).
2. Verify existence first with docstore.document_exists(doc_id).
3. Check the ID kind: for source documents use get_ref_doc_info / ref_doc collection; for nodes use the node_id.
4. Ensure the kvstore is persistent (e.g. MongoKVStore/RedisKVStore or SimpleKVStore + persist) if IDs were created in a previous run.

Example fix

# before
doc = docstore.get_document(doc_id)  # raises if missing

# after
doc = docstore.get_document(doc_id, raise_error=False)
if doc is None:
    # re-ingest or log-and-skip
    ...

def get_doc_or_none(docstore, doc_id):
    if not docstore.document_exists(doc_id):
        return None
    return docstore.get_document(doc_id)

def doc_exists(docstore, doc_id: str) -> bool:
    return docstore.document_exists(doc_id)

try:
    doc = docstore.get_document(doc_id)
except ValueError as e:
    if 'not found' in str(e):
        doc = None  # tolerate absence
    else:
        raise

When it happens

Trigger: docstore.get_document('some_id') where 'some_id' was never added or was deleted (delete_document / delete_ref_doc remove node entries too); also ID confusion such as querying with a ref_doc_id instead of the doc's own ID.

Common situations: Loading nodes by ID after partial deletion; querying a docstore backed by a fresh/ephemeral kvstore (in-memory SimpleKVStore) after a restart; stale IDs persisted in an external system pointing at cleared storage.

Related errors

• ref_doc_id {ref_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/3f40dd7f2cfda778. Report an issue: GitHub.