run-llama/llama_index · error · NotImplementedError

Cannot insert into an empty index.

Error message

Cannot insert into an empty index.

What it means

EmptyIndex deliberately holds no data: _build_index_from_nodes discards its nodes and returns an empty EmptyIndexStruct. Correspondingly, the mutation API is stubbed out — _insert() raises NotImplementedError, so any call that funnels into the base index's insert() path (e.g. index.insert(document)) fails on an EmptyIndex.

Source

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

        self, nodes: Sequence[BaseNode], **build_kwargs: Any
    ) -> EmptyIndexStruct:
        """
        Build the index from documents.

        Args:
            documents (List[BaseDocument]): A list of documents.

        Returns:
            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. Rebuild with a real index type that supports insertion, e.g. SummaryIndex.from_documents(docs) or VectorStoreIndex.from_documents(docs), if you need to add data.
2. Guard generic ingestion code: check isinstance(index, EmptyIndex) (or index type) and skip/replace insert() calls.
3. Recreate the EmptyIndex only at runtime when you truly want zero documents — never attempt incremental inserts into it.

Example fix

// before
empty_index.insert(new_doc)  # NotImplementedError

// after
from llama_index.core.indices import SummaryIndex
index = SummaryIndex.from_documents([new_doc])

from llama_index.core.indices.empty import EmptyIndex

assert not isinstance(index, EmptyIndex), "EmptyIndex does not support insert()"

from llama_index.core.indices.empty import EmptyIndex
from llama_index.core.indices.base import BaseIndex

def supports_insert(index: BaseIndex) -> bool:
    return not isinstance(index, EmptyIndex)

from llama_index.core.indices.empty import EmptyIndex
try:
    index.insert(doc)
except NotImplementedError:
    if isinstance(index, EmptyIndex):
        index = SummaryIndex.from_documents([doc])  # replace with data-bearing index
    else:
        raise

When it happens

Trigger: Calling empty_index.insert(document) or empty_index.insert_nodes(nodes) on an EmptyIndex; passing documents to EmptyIndex(nodes=...) or using insert_with_loader/refresh logic generic over index types against an EmptyIndex instance.

Common situations: Bootstrapping a 'chat-only' index then later trying to add documents incrementally; generic ingestion pipelines that call insert() on whatever index object they were handed; tests that reuse one fixture for multiple index classes.

Related errors

• Cannot delete from an empty index.
• ref_doc_info not supported for an empty index.
• _build_index_from_nodes 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/4a889f97f0e10bfb. Report an issue: GitHub.