run-llama/llama_index · error · ValueError

Invalid fusion mode: {self.mode}

Error message

Invalid fusion mode: {self.mode}

What it means

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.

Source

Thrown at llama-index-core/llama_index/core/retrievers/fusion_retriever.py:297

            queries.extend(self._get_queries(query_bundle.query_str))

        if self.use_async:
            results = self._run_nested_async_queries(queries)
        else:
            results = self._run_sync_queries(queries)

        if self.mode == FUSION_MODES.RECIPROCAL_RANK:
            return self._reciprocal_rerank_fusion(results)[: self.similarity_top_k]
        elif self.mode == FUSION_MODES.RELATIVE_SCORE:
            return self._relative_score_fusion(results)[: self.similarity_top_k]
        elif self.mode == FUSION_MODES.DIST_BASED_SCORE:
            return self._relative_score_fusion(results, dist_based=True)[
                : self.similarity_top_k
            ]
        elif self.mode == FUSION_MODES.SIMPLE:
            return self._simple_fusion(results)[: self.similarity_top_k]
        else:
            raise ValueError(f"Invalid fusion mode: {self.mode}")

    async def _aretrieve(self, query_bundle: QueryBundle) -> List[NodeWithScore]:
        queries: List[QueryBundle] = [query_bundle]
        if self.num_queries > 1:
            queries.extend(await self._aget_queries(query_bundle.query_str))

        results = await self._run_async_queries(queries)

        if self.mode == FUSION_MODES.RECIPROCAL_RANK:
            return self._reciprocal_rerank_fusion(results)[: self.similarity_top_k]
        elif self.mode == FUSION_MODES.RELATIVE_SCORE:
            return self._relative_score_fusion(results)[: self.similarity_top_k]
        elif self.mode == FUSION_MODES.DIST_BASED_SCORE:
            return self._relative_score_fusion(results, dist_based=True)[
                : self.similarity_top_k
            ]
        elif self.mode == FUSION_MODES.SIMPLE:
            return self._simple_fusion(results)[: self.similarity_top_k]

View on GitHub (pinned to afd0fef371)

Solutions

1. Pass the enum: from llama_index.core.retrievers import FUSION_MODES; mode=FUSION_MODES.RECIPROCAL_RANK.
2. If using a string, match the enum value exactly ('reciprocal_rank', 'relative_score', 'dist_based_score', 'simple').
3. Validate mode once at construction so you fail before burning LLM/sub-retriever calls.

Example fix

# before
retriever = QueryFusionRetriever(
    [...], mode="rrf", num_queries=4
)

# after
from llama_index.core.retrievers import FUSION_MODES
retriever = QueryFusionRetriever(
    [...], mode=FUSION_MODES.RECIPROCAL_RANK, num_queries=4
)

from llama_index.core.retrievers import FUSION_MODES
assert mode in list(FUSION_MODES), f"invalid fusion mode: {mode}"

from llama_index.core.retrievers import FUSION_MODES

def is_valid_fusion_mode(mode) -> bool:
    return mode in list(FUSION_MODES) or mode in [m.value for m in FUSION_MODES]

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unknown retriever mode: {retriever_mode}
• Unknown retriever mode: {retriever_mode}
• Unknown retriever mode: {retriever_mode}
• Unknown SQL parser mode: {sql_parser_mode}
• Unknown retriever mode: {retriever_mode}

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/db105157f817ad78. Report an issue: GitHub.