Haystack pipelines pass component results through named input and output sockets. A PipelineConnectError from Pipeline.connect() stops pipeline construction when two sockets declare incompatible types, and the declared types in the message show which connection to fix or convert.

A component's run() parameter annotations declare its input types, while @component.output_types declares its output types. Explicit socket names remove ambiguity about which values are connected, but selecting a name does not convert the values.

Haystack 3 supports limited implicit type adaptations, including wrapping a value in a list and converting between strings and chat messages. Extracting text from a list of Document objects still needs an explicit conversion. An OutputAdapter can join their contents into the string a downstream component expects without changing either component's interface.

Related: How to create a custom component in Haystack

Steps to troubleshoot PipelineConnectError in Haystack:

  1. Create a file named connect_error.py in your project using your text editor, starting with the imports and the DocumentSource component.
    connect_error.py
    from haystack import Document, Pipeline, component
from haystack.components.converters import OutputAdapter
 
 
@component
class DocumentSource:
    @component.output_types(documents=list[Document])
    def run(self):
        documents = [Document(content="Hello Haystack")]
        return {"documents": documents}

    The active Python environment needs the haystack-ai package. Tested with Python 3.12 and haystack-ai 3.4.1. The code uses local components without a model, API key, or external service.
    Related: How to install Haystack with pip

  2. Append the TextLength component at the end of connect_error.py. 
     
@component
class TextLength:
    @component.output_types(length=int)
    def run(self, text: str):
        return {"length": len(text)}

    The producer declares documents: list[Document], while the consumer requires text: str. These describe different data structures, even though each document contains text.

  3. Append the pipeline construction and direct connection at the end of connect_error.py. 
     
pipe = Pipeline()
pipe.add_component("source", DocumentSource())
pipe.add_component("length", TextLength())
pipe.connect("source.documents", "length.text")
  4. Save connect_error.py.
  5. Run connect_error.py to identify the incompatible sockets. 
    $ python connect_error.py
Traceback (most recent call last):
##### snipped #####
haystack.core.errors.PipelineConnectError: Cannot connect 'source.documents' with 'length.text': their declared input and output types do not match.
'source':
 - documents: list[Document]
'length':
 - text: str (available)

    The error names both ends of the failed connection and their declared types. In an existing pipeline, these declarations identify whether the wrong socket was selected or the data needs conversion. Changing documents to another name cannot make this document list a string. Other PipelineConnectError messages report different problems, such as a socket that does not exist.

  6. Open connect_error.py in your text editor.
  7. Replace the final pipe.connect("source.documents", "length.text") line with the adapter and connections below. 
    pipe.add_component(
    "to_text",
    OutputAdapter(
        template=(
            "{{ documents | map(attribute='content') "
            "| join('\\n') }}"
        ),
        output_type=str,
    ),
)
pipe.connect("source.documents", "to_text.documents")
pipe.connect("to_text.output", "length.text")
print(pipe.run({}))

    The template reads each document's content and joins the text with newlines. The adapter's output socket is declared as str to match length.text. A document without content, such as one that holds only a blob, adds the literal text None and raises no error. Changing only a type annotation would leave the underlying data unchanged.

  8. Save the updated connect_error.py.
  9. Rerun connect_error.py to confirm that the repaired pipeline returns the text length. 
    $ python connect_error.py
{'length': {'length': 14}}

    The number 14 is the character count of Hello Haystack after document-to-text conversion. This result shows that the connection was accepted and the downstream component consumed the converted value.

Share this guide