deepset-ai/haystack · error · ValueError

The provided `weights` must not sum to zero.

Error message

The provided `weights` must not sum to zero.

What it means

DocumentJoiner weights are normalized by their sum; if the provided weights sum to exactly zero the normalization would divide by zero, so __init__ raises ValueError. Weights can be negative individually but their total must be nonzero.

Source

Thrown at haystack/components/joiners/document_joiner.py:134

        :raises ValueError:
            If `top_k` is not `None` and is less than or equal to 0.
        """
        if top_k is not None and top_k <= 0:
            raise ValueError("top_k must be greater than 0.")
        if isinstance(join_mode, str):
            join_mode = JoinMode.from_str(join_mode)
        join_mode_functions = {
            JoinMode.CONCATENATE: DocumentJoiner._concatenate,
            JoinMode.MERGE: self._merge,
            JoinMode.RECIPROCAL_RANK_FUSION: self._rrf,
            JoinMode.DISTRIBUTION_BASED_RANK_FUSION: DocumentJoiner._distribution_based_rank_fusion,
        }
        self.join_mode_function = join_mode_functions[join_mode]
        self.join_mode = join_mode
        if weights:
            weight_sum = sum(weights)
            if weight_sum == 0:
                raise ValueError("The provided `weights` must not sum to zero.")
            self.weights: list[float] | None = [float(i) / weight_sum for i in weights]
        else:
            self.weights = None
        self.top_k = top_k
        self.sort_by_score = sort_by_score

    @component.output_types(documents=list[Document])
    def run(self, documents: Variadic[list[Document]], top_k: int | None = None) -> dict[str, Any]:
        """
        Joins multiple lists of Documents into a single list depending on the `join_mode` parameter.

        :param documents:
            List of list of documents to be merged.
        :param top_k:
            The maximum number of documents to return. Overrides the instance's `top_k` if provided.
            A value of 0 returns no documents. Must not be negative.

        :returns:

View on GitHub (pinned to e318778c9b)

Solutions

1. Adjust weights so their sum is nonzero (e.g. weights=[0.7, 0.3]).
2. Drop the weights argument entirely (weights=None) to skip weighting.
3. Validate sum(weights) != 0 before constructing the joiner.

Example fix

// before
DocumentJoiner(join_mode="merge", weights=[1, -1])
// after
DocumentJoiner(join_mode="merge", weights=[0.5, 0.5])

if weights and sum(weights) == 0:
    raise ValueError("weights must not sum to zero")
joiner = DocumentJoiner(weights=weights)

def are_valid_weights(w: list[float] | None) -> bool:
    return w is None or len(w) > 0 and sum(w) != 0

try:
    joiner = DocumentJoiner(weights=weights)
except ValueError as e:
    if "must not sum to zero" in str(e):
        joiner = DocumentJoiner(weights=None)
    else:
        raise

When it happens

Trigger: DocumentJoiner(weights=[1, -1]), weights=[0, 0, 0], or any list whose sum is 0.

Common situations: Balanced positive/negative weights that cancel out; all-zero placeholder weights; programmatically generated weights from differences that cancel.

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

• The following tool names are not valid: {invalid_tool_names}
• user_prompt must define exactly one message block, found {le
• system_prompt must define exactly one message block, found {
• Number of replies ({len(replies)}), and metadata ({len(meta)
• Pattern '{pattern}' contains multiple capture groups. Please

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