deepset-ai/haystack · error · ValueError

BranchJoiner expects only one input, but {inputs_count} were

Error message

BranchJoiner expects only one input, but {inputs_count} were received.

What it means

BranchJoiner forwards a single value to one of its branches, so exactly one connection may deliver input at runtime. run() raises ValueError when more than one value arrives on the 'value' input, because it cannot know which to forward.

Source

Thrown at haystack/components/joiners/branch.py:128

        Deserializes a `BranchJoiner` instance from a dictionary.

        :param data: The dictionary containing serialized component data.
        :returns:
            A deserialized `BranchJoiner` instance.
        """
        data["init_parameters"]["type_"] = deserialize_type(data["init_parameters"]["type_"])
        return default_from_dict(cls, data)

    def run(self, **kwargs: Any) -> dict[str, Any]:
        """
        Executes the `BranchJoiner`, selecting the first available input value and passing it downstream.

        :param **kwargs: The input data. Must be of the type declared by `type_` during initialization.
        :returns:
            A dictionary with a single key `value`, containing the first input received.
        """
        if (inputs_count := len(kwargs["value"])) != 1:
            raise ValueError(f"BranchJoiner expects only one input, but {inputs_count} were received.")
        return {"value": kwargs["value"][0]}

View on GitHub (pinned to e318778c9b)

Solutions

1. Inspect pipeline connections (pipeline.draw()/show()) and remove all but one edge into BranchJoiner.value.
2. Use a different component (e.g. DocumentJoiner or AnswerJoiner) if merging multiple inputs is intended.
3. Re-structure the pipeline with a Router component so only one sender fires per run.

Example fix

# before
pipeline.connect(router.unmatched, joiner.value)
pipeline.connect(other_comp.output, joiner.value)
// after
pipeline.connect(router.matched, joiner.value)  # only one connection to joiner.value

senders = [c for c in pipeline.connections() if c[1] == ("joiner", "value")]
if len(senders) > 1:
    raise ValueError(f"BranchJoiner.value must have exactly one sender, has {len(senders)}")

try:
    result = pipeline.run({"query": q})
except ValueError as e:
    if "BranchJoiner expects only one input" in str(e):
        raise RuntimeError("Pipeline mis-wired: multiple edges into BranchJoiner.value") from e
    raise

When it happens

Trigger: Wiring two or more components' outputs into BranchJoiner.value, then running the pipeline so multiple inputs arrive simultaneously (e.g. in a loop where two branches both emit).

Common situations: Pipeline mis-wiring in branching/looping graphs; connecting both a router output and another source to the same joiner input; forgetting that conditional execution still counts every connected sender that fires.

Related errors

• Document with ID '{doc.id}' comes from the PDF file '{resolv
• No `jq_schema` nor `content_key` specified. Set either or bo
• The MSG file is encrypted and cannot be read.
• Invalid Jinja template '{template}': {e}
• No input data provided for output adaptation

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