run-llama/llama_index · error · NotImplementedError

_build_index_from_nodes not implemented for BaseManagedIndex

Error message

_build_index_from_nodes not implemented for BaseManagedIndex.

What it means

BaseManagedIndex delegates the actual indexing to an external service (e.g. a managed vector platform), so building the index locally from nodes is not part of its contract. The class explicitly stubs _build_index_from_nodes with NotImplementedError so that any code path trying to construct index structures locally (e.g. base insert()/refit flows that call _build_index_from_nodes) fails loudly instead of silently creating an empty local index.

Source

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

    @abstractmethod
    def delete_ref_doc(
        self, ref_doc_id: str, delete_from_docstore: bool = False, **delete_kwargs: Any
    ) -> None:
        """Delete a document and it's nodes by using ref_doc_id."""

    @abstractmethod
    def update_ref_doc(self, document: Document, **update_kwargs: Any) -> None:
        """Update a document and it's corresponding nodes."""

    @abstractmethod
    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,

View on GitHub (pinned to afd0fef371)

Solutions

Use the managed index's own ingestion API — from_documents()/insert via the service client, or update_ref_doc for document updates — instead of local build/insert paths.
Check the concrete subclass (e.g. a managed vector-store integration) for supported operations; not all base-class methods apply.
If local construction is required, switch to VectorStoreIndex or SummaryIndex.

Example fix

# before
managed_index.insert_nodes(nodes)  # reaches _build_index_from_nodes -> NotImplementedError

# after
managed_index.update_ref_doc(document)  # managed-index ingestion path

Defensive patterns

Strategy: type-guard

Validate before calling

from llama_index.core.indices.managed import BaseManagedIndex

assert not isinstance(index, BaseManagedIndex), "managed indices do not support local node building"

Type guard

from llama_index.core.indices.managed import BaseManagedIndex

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

Try / catch

try:
    index.insert(doc)
except NotImplementedError as e:
    if "BaseManagedIndex" in str(e):
        index.update_ref_doc(doc)  # managed ingestion path
    else:
        raise

Prevention

Route ingestion for managed indices only through their documented service APIs.
Centralize index capability checks in one helper used by all pipelines.
When writing a managed-index integration, override the local-build stubs to raise clearer errors.

When it happens

Trigger: Calling insert()/insert_nodes() or any BaseIndex machinery on a managed index subclass that funnels into _build_index_from_nodes; invoking a generic indexing utility that assumes local node-based construction; subclassing BaseManagedIndex without delegating all ingestion to the remote service.

Common situations: Mixing local index APIs with managed index implementations; migrating code from VectorStoreIndex to a managed index and keeping insert() calls; authors of new managed-index integrations forgetting the base stubs.

Related errors

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