{"record":{"id":"4a889f97f0e10bfb","repo":"run-llama/llama_index","slug":"cannot-insert-into-an-empty-index","errorCode":null,"errorMessage":"Cannot insert into an empty index.","messagePattern":"Cannot insert into an empty index\\.","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/indices/empty/base.py","lineNumber":82,"sourceCode":"        self, nodes: Sequence[BaseNode], **build_kwargs: Any\n    ) -> EmptyIndexStruct:\n        \"\"\"\n        Build the index from documents.\n\n        Args:\n            documents (List[BaseDocument]): A list of documents.\n\n        Returns:\n            IndexList: The created summary index.\n\n        \"\"\"\n        del nodes  # Unused\n        return EmptyIndexStruct()\n\n    def _insert(self, nodes: Sequence[BaseNode], **insert_kwargs: Any) -> None:\n        \"\"\"Insert a document.\"\"\"\n        del nodes  # Unused\n        raise NotImplementedError(\"Cannot insert into an empty index.\")\n\n    def _delete_node(self, node_id: str, **delete_kwargs: Any) -> None:\n        \"\"\"Delete a node.\"\"\"\n        raise NotImplementedError(\"Cannot delete from an empty index.\")\n\n    @property\n    def ref_doc_info(self) -> Dict[str, RefDocInfo]:\n        \"\"\"Retrieve a dict mapping of ingested documents and their nodes+metadata.\"\"\"\n        raise NotImplementedError(\"ref_doc_info not supported for an empty index.\")\n\n\n# legacy\nGPTEmptyIndex = EmptyIndex\n","sourceCodeStart":64,"sourceCodeEnd":96,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/indices/empty/base.py#L64-L96","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Guard generic ingestion code: check isinstance(index, EmptyIndex) (or index type) and skip/replace insert() calls.","Recreate the EmptyIndex only at runtime when you truly want zero documents — never attempt incremental inserts into it."],"exampleFix":"// before\nempty_index.insert(new_doc)  # NotImplementedError\n\n// after\nfrom llama_index.core.indices import SummaryIndex\nindex = SummaryIndex.from_documents([new_doc])","handlingStrategy":"type-guard","validationCode":"from llama_index.core.indices.empty import EmptyIndex\n\nassert not isinstance(index, EmptyIndex), \"EmptyIndex does not support insert()\"","typeGuard":"from llama_index.core.indices.empty import EmptyIndex\nfrom llama_index.core.indices.base import BaseIndex\n\ndef supports_insert(index: BaseIndex) -> bool:\n    return not isinstance(index, EmptyIndex)","tryCatchPattern":"from llama_index.core.indices.empty import EmptyIndex\ntry:\n    index.insert(doc)\nexcept NotImplementedError:\n    if isinstance(index, EmptyIndex):\n        index = SummaryIndex.from_documents([doc])  # replace with data-bearing index\n    else:\n        raise","preventionTips":["Treat EmptyIndex as read-only chat scaffolding; keep insertion logic away from it.","In generic pipelines, branch on index type before mutating.","Document in your codebase which index types your ingestion path supports."],"tags":["llama-index","empty-index","not-implemented","insert"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}