{"record":{"id":"db105157f817ad78","repo":"run-llama/llama_index","slug":"invalid-fusion-mode-self-mode","errorCode":null,"errorMessage":"Invalid fusion mode: {self.mode}","messagePattern":"Invalid fusion mode: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/retrievers/fusion_retriever.py","lineNumber":297,"sourceCode":"            queries.extend(self._get_queries(query_bundle.query_str))\n\n        if self.use_async:\n            results = self._run_nested_async_queries(queries)\n        else:\n            results = self._run_sync_queries(queries)\n\n        if self.mode == FUSION_MODES.RECIPROCAL_RANK:\n            return self._reciprocal_rerank_fusion(results)[: self.similarity_top_k]\n        elif self.mode == FUSION_MODES.RELATIVE_SCORE:\n            return self._relative_score_fusion(results)[: self.similarity_top_k]\n        elif self.mode == FUSION_MODES.DIST_BASED_SCORE:\n            return self._relative_score_fusion(results, dist_based=True)[\n                : self.similarity_top_k\n            ]\n        elif self.mode == FUSION_MODES.SIMPLE:\n            return self._simple_fusion(results)[: self.similarity_top_k]\n        else:\n            raise ValueError(f\"Invalid fusion mode: {self.mode}\")\n\n    async def _aretrieve(self, query_bundle: QueryBundle) -> List[NodeWithScore]:\n        queries: List[QueryBundle] = [query_bundle]\n        if self.num_queries > 1:\n            queries.extend(await self._aget_queries(query_bundle.query_str))\n\n        results = await self._run_async_queries(queries)\n\n        if self.mode == FUSION_MODES.RECIPROCAL_RANK:\n            return self._reciprocal_rerank_fusion(results)[: self.similarity_top_k]\n        elif self.mode == FUSION_MODES.RELATIVE_SCORE:\n            return self._relative_score_fusion(results)[: self.similarity_top_k]\n        elif self.mode == FUSION_MODES.DIST_BASED_SCORE:\n            return self._relative_score_fusion(results, dist_based=True)[\n                : self.similarity_top_k\n            ]\n        elif self.mode == FUSION_MODES.SIMPLE:\n            return self._simple_fusion(results)[: self.similarity_top_k]","sourceCodeStart":279,"sourceCodeEnd":315,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/retrievers/fusion_retriever.py#L279-L315","documentation":"QueryFusionRetriever._fuse_results (sync path) dispatches on self.mode across FUSION_MODES members (RECIPROCAL_RANK, RELATIVE_SCORE, DIST_BASED_SCORE, SIMPLE) and raises ValueError for anything else at retrieval time, not construction time. A mode that is a plain string not matching an enum value, or a custom value, reaches this branch after all sub-retrievers have already run.","triggerScenarios":"QueryFusionRetriever(..., mode='reciprocal_rank_fusion') or another string that does not equal any FUSION_MODES value; typos like 'relative-score'; constructing with mode=FUSION_MODES.RECIPROCAL_RANK works but mode='RRF' does not; a custom constant passed from config.","commonSituations":"Mode strings copied from blog posts targeting other libraries (e.g. LlamaIndex tutorials vs LangChain 'rrf'); config-driven mode selection; version drift where mode names changed.","solutions":["Pass the enum: from llama_index.core.retrievers import FUSION_MODES; mode=FUSION_MODES.RECIPROCAL_RANK.","If using a string, match the enum value exactly ('reciprocal_rank', 'relative_score', 'dist_based_score', 'simple').","Validate mode once at construction so you fail before burning LLM/sub-retriever calls."],"exampleFix":"# before\nretriever = QueryFusionRetriever(\n    [...], mode=\"rrf\", num_queries=4\n)\n\n# after\nfrom llama_index.core.retrievers import FUSION_MODES\nretriever = QueryFusionRetriever(\n    [...], mode=FUSION_MODES.RECIPROCAL_RANK, num_queries=4\n)","handlingStrategy":"validation","validationCode":"from llama_index.core.retrievers import FUSION_MODES\nassert mode in list(FUSION_MODES), f\"invalid fusion mode: {mode}\"","typeGuard":"from llama_index.core.retrievers import FUSION_MODES\n\ndef is_valid_fusion_mode(mode) -> bool:\n    return mode in list(FUSION_MODES) or mode in [m.value for m in FUSION_MODES]","tryCatchPattern":null,"preventionTips":["Pass FUSION_MODES enum members, not free-form strings.","Validate mode at construction so failure happens before retrieval/LLM spend."],"tags":["retriever","fusion","enum","configuration"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}