{"record":{"id":"2095552ac7790e92","repo":"deepset-ai/haystack","slug":"the-provided-weights-must-not-sum-to-zero","errorCode":null,"errorMessage":"The provided `weights` must not sum to zero.","messagePattern":"The provided `weights` must not sum to zero\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"haystack/components/joiners/document_joiner.py","lineNumber":134,"sourceCode":"        :raises ValueError:\n            If `top_k` is not `None` and is less than or equal to 0.\n        \"\"\"\n        if top_k is not None and top_k <= 0:\n            raise ValueError(\"top_k must be greater than 0.\")\n        if isinstance(join_mode, str):\n            join_mode = JoinMode.from_str(join_mode)\n        join_mode_functions = {\n            JoinMode.CONCATENATE: DocumentJoiner._concatenate,\n            JoinMode.MERGE: self._merge,\n            JoinMode.RECIPROCAL_RANK_FUSION: self._rrf,\n            JoinMode.DISTRIBUTION_BASED_RANK_FUSION: DocumentJoiner._distribution_based_rank_fusion,\n        }\n        self.join_mode_function = join_mode_functions[join_mode]\n        self.join_mode = join_mode\n        if weights:\n            weight_sum = sum(weights)\n            if weight_sum == 0:\n                raise ValueError(\"The provided `weights` must not sum to zero.\")\n            self.weights: list[float] | None = [float(i) / weight_sum for i in weights]\n        else:\n            self.weights = None\n        self.top_k = top_k\n        self.sort_by_score = sort_by_score\n\n    @component.output_types(documents=list[Document])\n    def run(self, documents: Variadic[list[Document]], top_k: int | None = None) -> dict[str, Any]:\n        \"\"\"\n        Joins multiple lists of Documents into a single list depending on the `join_mode` parameter.\n\n        :param documents:\n            List of list of documents to be merged.\n        :param top_k:\n            The maximum number of documents to return. Overrides the instance's `top_k` if provided.\n            A value of 0 returns no documents. Must not be negative.\n\n        :returns:","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/components/joiners/document_joiner.py#L116-L152","documentation":"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.","triggerScenarios":"DocumentJoiner(weights=[1, -1]), weights=[0, 0, 0], or any list whose sum is 0.","commonSituations":"Balanced positive/negative weights that cancel out; all-zero placeholder weights; programmatically generated weights from differences that cancel.","solutions":["Adjust weights so their sum is nonzero (e.g. weights=[0.7, 0.3]).","Drop the weights argument entirely (weights=None) to skip weighting.","Validate sum(weights) != 0 before constructing the joiner."],"exampleFix":"// before\nDocumentJoiner(join_mode=\"merge\", weights=[1, -1])\n// after\nDocumentJoiner(join_mode=\"merge\", weights=[0.5, 0.5])","handlingStrategy":"validation","validationCode":"if weights and sum(weights) == 0:\n    raise ValueError(\"weights must not sum to zero\")\njoiner = DocumentJoiner(weights=weights)","typeGuard":"def are_valid_weights(w: list[float] | None) -> bool:\n    return w is None or len(w) > 0 and sum(w) != 0","tryCatchPattern":"try:\n    joiner = DocumentJoiner(weights=weights)\nexcept ValueError as e:\n    if \"must not sum to zero\" in str(e):\n        joiner = DocumentJoiner(weights=None)\n    else:\n        raise","preventionTips":["Check sum(weights) when mixing positive/negative weights","Prefer all-positive weights for clarity","Use weights=None to disable weighting entirely"],"tags":["validation","weights","haystack"],"backgroundTag":"invalid-parameter-value","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}