{"record":{"id":"ae0b4215a678c61c","repo":"run-llama/llama_index","slug":"node-id-node-id-not-found-in-index","errorCode":null,"errorMessage":"Node ID {node_id} not found in index. ","messagePattern":"Node ID (.+?) not found in index\\. ","errorType":"exception","errorClass":"KeyError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/indices/vector_store/retrievers/retriever.py","lineNumber":198,"sourceCode":"            unless the node was not found in the docstore, in which case we keep the original node.\n        \"\"\"\n        fetched_nodes_by_id: Dict[str, BaseNode] = {\n            str(node.node_id): node for node in fetched_nodes\n        }\n        new_nodes: List[BaseNode] = []\n\n        if query_result.nodes:\n            for node in list(query_result.nodes):\n                node_id_str = str(node.node_id)\n                if node_id_str in fetched_nodes_by_id:\n                    new_nodes.append(fetched_nodes_by_id[node_id_str])\n                else:\n                    # We did not fetch a replacement node, so we keep the original node\n                    new_nodes.append(node)\n        elif query_result.ids:\n            for node_id in query_result.ids:\n                if node_id not in self._index.index_struct.nodes_dict:\n                    raise KeyError(f\"Node ID {node_id} not found in index. \")\n                node_id_str = str(self._index.index_struct.nodes_dict[node_id])\n                if node_id_str in fetched_nodes_by_id:\n                    new_nodes.append(fetched_nodes_by_id[node_id_str])\n                else:\n                    raise KeyError(\n                        f\"Node ID {node_id_str} not found in fetched nodes. \"\n                    )\n        elif query_result.ids is None and query_result.nodes is None:\n            raise ValueError(\n                \"Vector store query result should return at least one of nodes or ids.\"\n            )\n        return new_nodes\n\n    def _convert_nodes_to_scored_nodes(\n        self, query_result: VectorStoreQueryResult\n    ) -> List[NodeWithScore]:\n        \"\"\"Create scored nodes from the vector store query result.\"\"\"\n        node_with_scores: List[NodeWithScore] = []","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/indices/vector_store/retrievers/retriever.py#L180-L216","documentation":"VectorIndexRetriever._build_nodes raises KeyError(f'Node ID {node_id} not found in index.') when the vector store returns ids in query_result.ids that are not keys in index.index_struct.nodes_dict. This path only runs when the store returns ids without nodes (stores_text=False): the retriever must map external ids to local nodes via the index struct. A mismatch means the vector store contains vectors whose ids were never registered in this index's nodes_dict — e.g. data written by a different run/index or the index struct not persisted alongside the vector store.","triggerScenarios":"Vector store pre-populated outside this index (external upserts, another service, another llama-index project) then queried through VectorIndexRetriever; reloading an index where the vector store persisted but the index_struct/docstore did not; partial deletes leaving stale ids in the store.","commonSituations":"Chroma/Milvus/FAISS files shared across runs; hybrid setups where a separate pipeline writes embeddings; storage_context persist_dir missing .json artifacts while the vector DB retained data.","solutions":["Make the vector store and index struct consistent: clear the store and re-ingest through the same VectorStoreIndex so nodes_dict and store ids match.","When reloading, load the full storage context (index_struct + docstore) that was persisted with that vector store, not just the vector store.","If the store must be shared, use a stores_text=True store so query results carry nodes and the nodes_dict mapping is bypassed."],"exampleFix":"# before\n# chroma persisted earlier by another run; index_struct is empty\nretriever = VectorIndexRetriever(index)\nnodes = retriever.retrieve(\"query\")  # KeyError: Node ID ... not found in index\n\n# after\nstore.clear()  # or a fresh collection\nindex = VectorStoreIndex.from_documents(docs, storage_context=StorageContext.from_defaults(vector_store=store))\nnodes = index.as_retriever().retrieve(\"query\")","handlingStrategy":"try-catch","validationCode":"def store_ids_all_registered(store, index) -> bool:\n    \"\"\"Heavier check; do a cheap canary retrieve instead.\"\"\"\n    return True\n\ndef canary_retrieve_ok(retriever, index) -> bool:\n    try:\n        retriever.retrieve(\"__canary__\")\n        return True\n    except KeyError:\n        return False  # vector store contains ids unknown to index_struct","typeGuard":null,"tryCatchPattern":"try:\n    nodes = retriever.retrieve(query_str)\nexcept KeyError as e:\n    if \"not found in index\" in str(e):\n        # store/index_struct mismatch: re-sync or rebuild\n        index = resync_index_from_store(index)\n        nodes = index.as_retriever().retrieve(query_str)\n    else:\n        raise","preventionTips":["Always write vector store and index_struct/docstore through the same StorageContext in one run.","Never upsert vectors into the store externally and expect the retriever to resolve those ids.","On 'KeyError: Node ID ... not found in index', treat it as data drift: clean + re-ingest rather than patching."],"tags":["vector-store","storage-consistency","retriever","llama-index"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}