run-llama/llama_index · error · NotImplementedError

ref_doc_info not implemented for BaseManagedIndex.

Error message

ref_doc_info not implemented for BaseManagedIndex.

What it means

ref_doc_info reports which source documents were ingested and their node mappings — state that lives in the external service for a managed index, not locally. BaseManagedIndex therefore implements the ref_doc_info property as a NotImplementedError stub, so merely reading it raises.

Source

Thrown at llama-index-core/llama_index/core/indices/managed/base.py:83

    def as_retriever(self, **kwargs: Any) -> BaseRetriever:
        """Return a Retriever for this managed index."""

    def _build_index_from_nodes(
        self, nodes: Sequence[BaseNode], **build_kwargs: Any
    ) -> IndexDict:
        """Build the index from nodes."""
        raise NotImplementedError(
            "_build_index_from_nodes not implemented for BaseManagedIndex."
        )

    def _delete_node(self, node_id: str, **delete_kwargs: Any) -> None:
        """Delete a node."""
        raise NotImplementedError("_delete_node not implemented for BaseManagedIndex.")

    @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 implemented for BaseManagedIndex.")

    @classmethod
    def from_documents(
        cls: Type[IndexType],
        documents: Sequence[Document],
        storage_context: Optional[StorageContext] = None,
        show_progress: bool = False,
        callback_manager: Optional[CallbackManager] = None,
        transformations: Optional[List[TransformComponent]] = None,
        **kwargs: Any,
    ) -> IndexType:
        """Build an index from a sequence of documents."""
        raise NotImplementedError(
            "from_documents not implemented for BaseManagedIndex."
        )

View on GitHub (pinned to afd0fef371)

Solutions

  1. Query the external service directly (its client/API) for ingested-document information instead of ref_doc_info.
  2. Maintain your own document registry (DB table) at ingestion time when you need this metadata for managed indices.
  3. Wrap access in try/except NotImplementedError for registries mixing local and managed index types.

Example fix

# before
info = managed_index.ref_doc_info  # raises

# after
info = my_doc_registry.list_docs(managed_index.index_id)  # track externally
Defensive patterns

Strategy: try-catch

Validate before calling

from llama_index.core.indices.managed import BaseManagedIndex

if isinstance(index, BaseManagedIndex):
    info = doc_registry.list_docs(index.index_id)  # external tracking
else:
    info = index.ref_doc_info

Type guard

from llama_index.core.indices.managed import BaseManagedIndex

def has_local_ref_doc_info(index: object) -> bool:
    return not isinstance(index, BaseManagedIndex)

Try / catch

try:
    info = index.ref_doc_info
except NotImplementedError:
    info = {}  # managed index: query the external service instead

Prevention

When it happens

Trigger: Accessing managed_index.ref_doc_info (a property — no call needed); admin tooling that lists ingested docs per index across a registry; sync scripts diffing ref_doc_info against external sources.

Common situations: Dashboards/audit tooling written against local indices and later pointed at a managed one; compliance features that enumerate ingested documents; forgetting that managed indices externalize all state.

Related errors

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