deepset-ai/haystack · error · PipelineConnectError

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

Error message

Cannot connect '${sender_component_name}' with '${receiver_component_name}': their declared input and output types do not match.\n${status} | Cannot connect '${sender_component_name}' with '${receiver_component_name}': no matching connections available.\n${status}

What it means

Pipeline.connect() raises PipelineConnectError when no connection between sender and receiver matches by type. Either the declared types are incompatible ('their declared input and output types do not match') or no possible connections remain after filtering ('no matching connections available'); `status` describes which sockets are free/occupied.

Source

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

            sender_sockets=sender_socket_candidates,
            receiver_node=receiver_component_name,
            receiver_sockets=receiver_socket_candidates,
        )

        if not possible_connections:
            # There's no possible connection between these two components
            if len(sender_socket_candidates) == len(receiver_socket_candidates) == 1:
                msg = (
                    f"Cannot connect '{sender_component_name}.{sender_socket_candidates[0].name}' with "
                    f"'{receiver_component_name}.{receiver_socket_candidates[0].name}': "
                    f"their declared input and output types do not match.\n{status}"
                )
            else:
                msg = (
                    f"Cannot connect '{sender_component_name}' with '{receiver_component_name}': "
                    f"no matching connections available.\n{status}"
                )
            raise PipelineConnectError(msg)

        if len(possible_connections) == 1:
            # There's only one possible connection, use it
            sender_socket = possible_connections[0][0]
            receiver_socket = possible_connections[0][1]
            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 "

View on GitHub (pinned to e318778c9b)

Solutions

Check the declared types of the sockets (shown in the error status) and reorder or insert an adapter component between them
Choose a different receiver input socket that matches the sender's output type
Use a conversion bridge (e.g. OutputAdapter) to convert types
If inputs are occupied, disconnect the conflicting connection or pick another free input

Example fix

// before
pipeline.connect('retriever', 'text_embedder')  # documents -> text mismatch
// after
from haystack.components.converters import OutputAdapter
pipeline.add_component('adapter', OutputAdapter(template='{{ documents[0].content }}', output_type=str))
pipeline.connect('retriever', 'adapter')
pipeline.connect('adapter', 'text_embedder')

Defensive patterns

Strategy: validation

Validate before calling

from haystack.core.type_utils import _type_name
comp_s = pipeline.get_component(sender)
comp_r = pipeline.get_component(receiver)
out_types = [s.type for s in comp_s.__haystack_output__._sockets_dict.values()]
in_types = [s.type for s in comp_r.__haystack_input__._sockets_dict.values()]
print(f'{sender} outputs: {out_types} -> {receiver} inputs: {in_types}')  # verify compatibility manually before connect

Type guard

def types_compatible(out_type, in_type) -> bool:
    return out_type == in_type or (isinstance(out_type, type) and isinstance(in_type, type) and issubclass(out_type, in_type))

Try / catch

try:
    pipeline.connect(sender, receiver)
except PipelineConnectError as e:
    if 'do not match' in str(e) or 'no matching connections' in str(e):
        raise TypeError(f'Incompatible sockets {sender}->{receiver}; insert an OutputAdapter') from e

Prevention

Check declared input/output types of components before wiring
Insert OutputAdapter when types differ
Keep pipeline topologies simple and test connectivity in unit tests

When it happens

Trigger: Connecting components whose output type is not compatible with the receiver's input type (no subtyping and no lazy variadic match), or all candidate receiver inputs are already occupied by other connections.

Common situations: Swapping component order (e.g. retriever output fed into an embedder expecting text); connecting a component to itself in the wrong direction; all compatible inputs already taken by earlier connect() calls; using a custom component with mismatched declared types.

Related errors

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