deepset-ai/haystack · error · ValueError

Parameter <weight> must be in range [0,1] but is currently s

Error message

Parameter <weight> must be in range [0,1] but is currently set to '{weight}'.
'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.
Change the <weight> parameter to a value in range 0 to 1 when initializing the MetaFieldRanker.

What it means

MetaFieldRanker._validate_params rejects a weight outside [0, 1]. Weight blends relevance scores with the meta-field sort: 0 ignores the meta field, 0.5 mixes equally, 1 ranks purely by the meta field. Values outside this range are semantically invalid and raise ValueError.

Source

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

            meta_value_type=meta_value_type,
        )
        self.meta_value_type = meta_value_type

    def _validate_params(
        self,
        *,
        weight: float,
        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 "

View on GitHub (pinned to e318778c9b)

Solutions

1. Set weight to a float in [0,1], e.g. MetaFieldRanker(weight=0.5).
2. Normalize/clip the value before construction: weight = min(1.0, max(0.0, weight)).
3. If the intent was a percentage, divide by 100 first.

Example fix

// before
ranker = MetaFieldRanker(weight=100)  # meant 100%
// after
ranker = MetaFieldRanker(weight=1.0)

if not (0 <= weight <= 1):
    raise ValueError(f"weight must be in [0,1], got {weight}")

def is_valid_weight(v) -> bool:
    return isinstance(v, (int, float)) and 0 <= v <= 1

try:
    ranker = MetaFieldRanker(weight=w)
except ValueError:
    ranker = MetaFieldRanker(weight=min(1.0, max(0.0, w)))

When it happens

Trigger: MetaFieldRanker(weight=1.5), weight=-0.1, or a run() override with an out-of-range value; validation runs in both __init__ and run.

Common situations: Confusing weight with a percentage and passing 100 or 50 instead of 1.0/0.5; multiplying weights across components and drifting above 1; parsing config strings into floats without range checks.

Understand the failure class

Background: "must be positive", "Invalid value": how libraries reject invalid parameter values (ValueError, ArgumentError, INVALID_PARAMETER_VALUE) — this error's family across 28 libraries.

Related errors

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

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