{"record":{"id":"81c63e9bb5e09906","repo":"run-llama/llama_index","slug":"retrieved-more-than-one-node","errorCode":null,"errorMessage":"Retrieved more than one node.","messagePattern":"Retrieved more than one node\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/query_engine/router_query_engine.py","lineNumber":306,"sourceCode":"        self,\n        retriever: BaseRetriever,\n        node_to_query_engine_fn: Callable,\n        callback_manager: Optional[CallbackManager] = None,\n    ) -> None:\n        self._retriever = retriever\n        self._node_to_query_engine_fn = node_to_query_engine_fn\n        super().__init__(callback_manager)\n\n    def _get_prompt_modules(self) -> PromptMixinType:\n        \"\"\"Get prompt sub-modules.\"\"\"\n        # NOTE: don't include tools for now\n        return {\"retriever\": self._retriever}\n\n    def _query(self, query_bundle: QueryBundle) -> RESPONSE_TYPE:\n        nodes_with_score = self._retriever.retrieve(query_bundle)\n        # TODO: for now we only support retrieving one node\n        if len(nodes_with_score) > 1:\n            raise ValueError(\"Retrieved more than one node.\")\n\n        node = nodes_with_score[0].node\n        query_engine = self._node_to_query_engine_fn(node)\n        return query_engine.query(query_bundle)\n\n    async def _aquery(self, query_bundle: QueryBundle) -> RESPONSE_TYPE:\n        return self._query(query_bundle)\n\n\nclass ToolRetrieverRouterQueryEngine(BaseQueryEngine):\n    \"\"\"\n    Tool Retriever router query engine.\n\n    Selects a set of candidate query engines to execute a query.\n\n    Args:\n        retriever (ObjectRetriever): A retriever that retrieves a set of\n            query engine tools.","sourceCodeStart":288,"sourceCodeEnd":324,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/query_engine/router_query_engine.py#L288-L324","documentation":"RetrieverRouterQueryEngine (deprecated) routes by retrieving exactly one node that maps to a query engine. Its _query currently supports only a single result: if the retriever returns more than one node, it raises ValueError('Retrieved more than one node.') instead of choosing among them.","triggerScenarios":"Calling query()/aquery() on RetrieverRouterQueryEngine where the underlying retriever's top_k (default 2 or more, or similarity_top_k) yields multiple nodes above the threshold.","commonSituations":"Forgetting to set similarity_top_k=1 on the router's retriever; storing many tool-description nodes in the routing index so several match the query.","solutions":["Construct the routing retriever with top_k=1: RetrieverRouterQueryEngine(index.as_retriever(similarity_top_k=1), ...)","Keep exactly one node per query engine in the routing index","Migrate to ToolRetrieverRouterQueryEngine, which handles multiple retrieved tools"],"exampleFix":"// before\nrouter = RetrieverRouterQueryEngine(\n    retriever=routing_index.as_retriever(),  # default top_k > 1\n    node_to_query_engine_fn=fn,\n)\n\n// after\nrouter = RetrieverRouterQueryEngine(\n    retriever=routing_index.as_retriever(similarity_top_k=1),\n    node_to_query_engine_fn=fn,\n)","handlingStrategy":"validation","validationCode":"retriever = routing_index.as_retriever(similarity_top_k=1)\nrouter = RetrieverRouterQueryEngine(retriever=retriever, node_to_query_engine_fn=fn)\n\n# belt and braces: dry-run retrieve to confirm single result\nresult = retriever.retrieve(QueryBundle(query_str=\"sample query\"))\nassert len(result) <= 1, f\"router retriever returned {len(result)} nodes\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set similarity_top_k=1 on the routing retriever","Keep one description node per query engine in the routing index","Migrate to ToolRetrieverRouterQueryEngine which tolerates multiple retrieved tools"],"tags":["router","retriever","top-k","deprecated"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}