{"record":{"id":"9cc26413d95d303f","repo":"run-llama/llama_index","slug":"vector-store-query-result-should-return-at-least-o-9cc264","errorCode":null,"errorMessage":"Vector store query result should return at least one of nodes or ids.","messagePattern":"Vector store query result should return at least one of nodes or ids\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/indices/vector_store/retrievers/retriever.py","lineNumber":207,"sourceCode":"                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] = []\n\n        for ind, node in enumerate(list(query_result.nodes or [])):\n            score: Optional[float] = None\n            if query_result.similarities is not None:\n                score = query_result.similarities[ind]\n\n            node_with_scores.append(NodeWithScore(node=node, score=score))\n\n        return node_with_scores","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/indices/vector_store/retrievers/retriever.py#L189-L225","documentation":"VectorIndexRetriever._build_nodes raises ValueError('Vector store query result should return at least one of nodes or ids.') when the VectorStoreQueryResult returned by the vector store has both nodes=None and ids=None (empty query results are fine — they are lists — but a result carrying neither field at all is not). This indicates a custom or buggy vector store integration whose query() builds VectorStoreQueryResult() without populating nodes/ids, since the built-in stores always set at least ids.","triggerScenarios":"Implementing a custom BasePydanticVectorStore whose query() returns VectorStoreQueryResult() or only similarities; an integration version whose query path returns a bare result object on error/empty; monkeypatched stores in tests returning incomplete results.","commonSituations":"Writing a new vector store integration and forgetting to attach ids; test doubles that construct VectorStoreQueryResult() with only similarities; early-access integration releases with unpopulated fields on edge cases.","solutions":["In the custom store's query(), always populate ids (and nodes when available): VectorStoreQueryResult(nodes=nodes or [], ids=[n.node_id for n in nodes], similarities=similarities).","Upgrade the integration package if this comes from a third-party store — check its query implementation.","Return empty lists rather than None for zero matches."],"exampleFix":"# before (custom store)\ndef query(self, query, **kwargs):\n    sims = self._search(query.query_embedding)\n    return VectorStoreQueryResult(similarities=sims)  # ValueError upstream\n\n# after\ndef query(self, query, **kwargs):\n    nodes, sims = self._search(query.query_embedding)\n    return VectorStoreQueryResult(\n        nodes=nodes,\n        ids=[n.node_id for n in nodes],\n        similarities=sims,\n    )","handlingStrategy":"validation","validationCode":"from llama_index.core.vector_stores.types import VectorStoreQueryResult\n\ndef query_result_is_valid(r: VectorStoreQueryResult) -> bool:\n    return r.nodes is not None or r.ids is not None","typeGuard":"def has_nodes_or_ids(result) -> bool:\n    return result is not None and (result.nodes is not None or result.ids is not None)","tryCatchPattern":"try:\n    nodes = retriever.retrieve(query_str)\nexcept ValueError as e:\n    if \"at least one of nodes or ids\" in str(e):\n        raise TypeError(\"custom vector store query() must populate nodes or ids\") from e\n    raise","preventionTips":["Custom vector stores: always return ids (and nodes when stored) in VectorStoreQueryResult — empty lists, never None.","Unit-test your store's query() against VectorIndexRetriever, including the zero-match case.","Keep third-party integrations current; this error usually means an integration bug."],"tags":["vector-store","custom-integration","api-contract","llama-index"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}