deepset-ai/haystack · error · PipelineConnectError

Cannot connect '${sender_component_name}' with '${receiver_c

Error message

Cannot connect '${sender_component_name}' with '${receiver_component_name}': more than one connection is possible between these components. Please specify the connection name, like: pipeline.connect('${sender_component_name}.${socket}', '${receiver_component_name}.${socket}').\n${status}

What it means

Pipeline.connect() raises PipelineConnectError when more than one sender/receiver socket pair could be connected (e.g. both components have multiple variadic or compatible type-matched sockets). Haystack refuses to guess and asks you to name the sockets explicitly.

Source

Thrown at haystack/core/pipeline/base.py:738

            conversion_strategy = possible_connections[0][2]

        if len(possible_connections) > 1:
            # There are multiple possible connection, let's try to match them by name
            name_matches = [
                (out_sock, in_sock, conversion_strategy_)
                for out_sock, in_sock, conversion_strategy_ in possible_connections
                if in_sock.name == out_sock.name
            ]
            if len(name_matches) != 1:
                # There's are either no matches or more than one, we can't pick one reliably
                msg = (
                    f"Cannot connect '{sender_component_name}' with "
                    f"'{receiver_component_name}': more than one connection is possible "
                    "between these components. Please specify the connection name, like: "
                    f"pipeline.connect('{sender_component_name}.{possible_connections[0][0].name}', "
                    f"'{receiver_component_name}.{possible_connections[0][1].name}').\n{status}"
                )
                raise PipelineConnectError(msg)

            # Get the only possible match
            sender_socket = name_matches[0][0]
            receiver_socket = name_matches[0][1]
            conversion_strategy = name_matches[0][2]

        # Connection must be valid on both sender/receiver sides
        if not sender_socket or not receiver_socket or not sender_component_name or not receiver_component_name:
            if sender_component_name and sender_socket:
                sender_repr = f"{sender_component_name}.{sender_socket.name} ({_type_name(sender_socket.type)})"
            else:
                sender_repr = "input needed"

            if receiver_component_name and receiver_socket:
                receiver_repr = f"({_type_name(receiver_socket.type)}) {receiver_component_name}.{receiver_socket.name}"
            else:
                receiver_repr = "output"
            msg = f"Connection must have both sender and receiver: {sender_repr} -> {receiver_repr}"

View on GitHub (pinned to e318778c9b)

Solutions

1. Specify both socket names explicitly: pipeline.connect('sender.socket_a', 'receiver.socket_b')
2. Use the exact names suggested in the error message for the first possible pair
3. If a socket pair is ambiguous due to optional/variadic matches, add a type hint or OutputAdapter to disambiguate

Example fix

// before
pipeline.connect('llm', 'prompt_builder')
// after
pipeline.connect('llm.replies', 'prompt_builder.prompt')

comp_s = pipeline.get_component(sender)
comp_r = pipeline.get_component(receiver)
if len(comp_s.__haystack_output__._sockets_dict) > 1 or len(comp_r.__haystack_input__._sockets_dict) > 1:
    raise ValueError('Multiple sockets: use explicit sender.socket / receiver.socket names')

def is_unambiguous(sender_comp, receiver_comp) -> bool:
    return len(sender_comp.__haystack_output__._sockets_dict) <= 1 and len(receiver_comp.__haystack_input__._sockets_dict) <= 1

try:
    pipeline.connect(sender, receiver)
except PipelineConnectError as e:
    if 'more than one connection' in str(e):
        raise ValueError(f'Ambiguous: call pipeline.connect("{sender}.<out>", "{receiver}.<in>")') from e

When it happens

Trigger: Connecting two components that each have several compatible sockets (common with components having variadic inputs or LLM components with multiple chat/string outputs) without using the 'component.socket' notation.

Common situations: Connecting Agent/ChatGenerator outputs (multiple replies-like sockets) to a PromptBuilder; generative components with several matching outputs; components with both 'query' and 'documents' type-compatible paths.

Related errors

• MarkdownHeaderSplitter only works with text documents but co
• set_input_types()/set_input_type() cannot override the param
• Cannot set input types on a component that doesn't have a kw
• Cannot call `set_output_types` on a component that already h
• Missing 'type' in component '{name}'

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