run-llama/llama_index · error · NotImplementedError

ref_doc_info not supported for an empty index.

Error message

ref_doc_info not supported for an empty index.

What it means

ref_doc_info maps ingested source documents to their nodes and metadata — a concept that cannot exist for an index that ingests nothing. EmptyIndex implements the ref_doc_info property as a raise, so even reading it (not calling it) raises NotImplementedError.

Source

Thrown at llama-index-core/llama_index/core/indices/empty/base.py:91

            IndexList: The created summary index.

        """
        del nodes  # Unused
        return EmptyIndexStruct()

    def _insert(self, nodes: Sequence[BaseNode], **insert_kwargs: Any) -> None:
        """Insert a document."""
        del nodes  # Unused
        raise NotImplementedError("Cannot insert into an empty index.")

    def _delete_node(self, node_id: str, **delete_kwargs: Any) -> None:
        """Delete a node."""
        raise NotImplementedError("Cannot delete from an empty index.")

    @property
    def ref_doc_info(self) -> Dict[str, RefDocInfo]:
        """Retrieve a dict mapping of ingested documents and their nodes+metadata."""
        raise NotImplementedError("ref_doc_info not supported for an empty index.")


# legacy
GPTEmptyIndex = EmptyIndex

View on GitHub (pinned to afd0fef371)

Solutions

1. Guard property access: check isinstance(index, EmptyIndex) (or try/except NotImplementedError) before touching ref_doc_info.
2. Track ingested document metadata externally (your DB/docstore) when an EmptyIndex may be in play, since the index itself cannot report it.
3. Use a data-bearing index (SummaryIndex/VectorStoreIndex) if introspection of ingested docs is a requirement.

Example fix

// before
info = index.ref_doc_info  # raises on EmptyIndex

// after
from llama_index.core.indices.empty import EmptyIndex
info = {} if isinstance(index, EmptyIndex) else index.ref_doc_info

from llama_index.core.indices.empty import EmptyIndex

info = {} if isinstance(index, EmptyIndex) else index.ref_doc_info

from llama_index.core.indices.empty import EmptyIndex

def has_ref_doc_info(index: object) -> bool:
    return not isinstance(index, EmptyIndex)

try:
    info = index.ref_doc_info
except NotImplementedError:
    info = {}  # empty/managed index: no ingested doc info

When it happens

Trigger: Accessing empty_index.ref_doc_info (property access, no call); generic bookkeeping code that iterates index.ref_doc_info to list ingested docs; calling index_utils helpers like get_node_list/get_source_doc_info on an EmptyIndex.

Common situations: Admin dashboards showing which documents each index contains; document-sync tooling that diffs ref_doc_info against an external store; reusable maintenance scripts applied to every index in a registry.

Related errors

• Cannot insert into an empty index.
• Cannot delete from an empty index.
• ref_doc_info not implemented for BaseManagedIndex.
• EmptyIndex only supports response_mode=generation.
• Delete is not supported for KG index yet.

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