deepset-ai/haystack · error · ValueError

The value of parameter <ranking_mode> must be 'reciprocal_ra

Error message

The value of parameter <ranking_mode> must be 'reciprocal_rank_fusion' or 'linear_score', but is currently set to '{ranking_mode}'.
Change the <ranking_mode> value to 'reciprocal_rank_fusion' or 'linear_score' when initializing the MetaFieldRanker.

What it means

MetaFieldRanker._validate_params rejects any ranking_mode other than 'reciprocal_rank_fusion' or 'linear_score'. This literal-typed parameter selects the score-combination algorithm; an unknown value cannot be dispatched and raises ValueError in both __init__ and run.

Source

Thrown at haystack/components/rankers/meta_field.py:132

        top_k: int | None,
        ranking_mode: Literal["reciprocal_rank_fusion", "linear_score"],
        sort_order: Literal["ascending", "descending"],
        missing_meta: Literal["drop", "top", "bottom"],
        meta_value_type: Literal["float", "int", "date"] | None,
    ) -> None:
        if top_k is not None and top_k <= 0:
            raise ValueError(f"top_k must be > 0, but got {top_k}")

        if weight < 0 or weight > 1:
            raise ValueError(
                f"Parameter <weight> must be in range [0,1] but is currently set to '{weight}'.\n'0' disables sorting "
                "by a meta field, '0.5' assigns equal weight to the previous relevance scores and the meta field, and "
                "'1' ranks by the meta field only.\nChange the <weight> parameter to a value in range 0 to 1 when "
                "initializing the MetaFieldRanker."
            )

        if ranking_mode not in ["reciprocal_rank_fusion", "linear_score"]:
            raise ValueError(
                "The value of parameter <ranking_mode> must be 'reciprocal_rank_fusion' or 'linear_score', but is "
                f"currently set to '{ranking_mode}'.\nChange the <ranking_mode> value to 'reciprocal_rank_fusion' or "
                "'linear_score' when initializing the MetaFieldRanker."
            )

        if sort_order not in ["ascending", "descending"]:
            raise ValueError(
                "The value of parameter <sort_order> must be 'ascending' or 'descending', "
                f"but is currently set to '{sort_order}'.\n"
                "Change the <sort_order> value to 'ascending' or 'descending' when initializing the "
                "MetaFieldRanker."
            )

        if missing_meta not in ["drop", "top", "bottom"]:
            raise ValueError(
                "The value of parameter <missing_meta> must be 'drop', 'top', or 'bottom', "
                f"but is currently set to '{missing_meta}'.\n"
                "Change the <missing_meta> value to 'drop', 'top', or 'bottom' when initializing the "

View on GitHub (pinned to e318778c9b)

Solutions

1. Use exactly 'reciprocal_rank_fusion' or 'linear_score' (lowercase).
2. Compare against the Literal type in the component's signature or docs and fix the spelling.
3. If the value comes from config, map/normalize it before constructing the ranker.

Example fix

// before
ranker = MetaFieldRanker(ranking_mode="rrf")
// after
ranker = MetaFieldRanker(ranking_mode="reciprocal_rank_fusion")

VALID_RANKING_MODES = ("reciprocal_rank_fusion", "linear_score")
if ranking_mode not in VALID_RANKING_MODES:
    raise ValueError(f"ranking_mode must be one of {VALID_RANKING_MODES}, got {ranking_mode!r}")

def is_valid_ranking_mode(v) -> bool:
    return v in ("reciprocal_rank_fusion", "linear_score")

try:
    ranker = MetaFieldRanker(ranking_mode=mode)
except ValueError as e:
    logger.warning("Invalid ranking_mode %s; defaulting to reciprocal_rank_fusion", e)
    ranker = MetaFieldRanker(ranking_mode="reciprocal_rank_fusion")

When it happens

Trigger: MetaFieldRanker(ranking_mode='rrf'), 'score', 'linear', or any misspelled/unrelated string; typing only catches this statically with a type checker, not at runtime.

Common situations: Abbreviating mode names in configs ('rrf'); copying a mode string from another ranker component (e.g. a SentimentRanker option); YAML values with different casing ('Linear_Score').

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• The value of parameter <sort_order> must be 'ascending' or '
• The value of parameter <missing_meta> must be 'drop', 'top',
• Invalid value for word_count_threshold: {word_count_threshol
• top_k must be > 0, but got {top_k}
• top_k must be > 0, but got {top_k}

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/30b3be22c0209332. Report an issue: GitHub.