deepset-ai/haystack · error · ValueError

Missing mandatory input '${socket_name}' for component '${co

Error message

Missing mandatory input '${socket_name}' for component '${component_name}'.

What it means

validate_input() raises this ValueError when a component in the pipeline has a mandatory input socket (is_mandatory) with no sender connected and the caller did not supply it in the run() input dict. The pipeline checks every component before executing so failures surface up front rather than mid-run.

Source

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

            If inputs are invalid according to the above.
        """
        for component_name, component_inputs in data.items():
            # Check that the component exists
            if component_name not in self.graph.nodes:
                raise ValueError(f"Component named '{component_name}' not found in the pipeline.")
            # Check that no input is provided that the component can't accept
            instance = self.graph.nodes[component_name]["instance"]
            for input_name in component_inputs.keys():
                if input_name not in instance.__haystack_input__._sockets_dict:
                    raise ValueError(f"Input '{input_name}' not found in component '{component_name}'.")

        for component_name in self.graph.nodes:
            instance = self.graph.nodes[component_name]["instance"]
            for socket_name, socket in instance.__haystack_input__._sockets_dict.items():
                component_inputs = data.get(component_name, {})
                # Check that no mandatory input is missing for any component in the pipeline
                if socket.senders == [] and socket.is_mandatory and socket_name not in component_inputs:
                    raise ValueError(f"Missing mandatory input '{socket_name}' for component '{component_name}'.")

                # Check if an input is provided more than once for non-variadic sockets
                if socket.senders and socket_name in component_inputs:
                    self._make_socket_auto_variadic(
                        component_name=component_name, receiver_socket=socket, error_type=ValueError
                    )

    def _make_socket_auto_variadic(
        self, component_name: str, receiver_socket: InputSocket, error_type: type[Exception]
    ) -> InputSocket:
        """
        Attempts to make the receiver socket lazy variadic in-place to accommodate a new sender.

        A socket is automatically made lazy variadic when:
          - It already has at least one connected sender
          - It is not already variadic
          - Its type is list, Optional[list], a union of list types

View on GitHub (pinned to e318778c9b)

Solutions

Add the missing key to the run() input dict: pipeline.run({"<component>": {"<socket_name>": value}}).
Connect a sender to the socket with pipeline.connect(src_component.src_socket, "<component>", "<socket_name>") so it is no longer unconnected.
If the value is legitimately optional in your use, set a default in the component definition (InputSocket default) or declare it is_mandatory=False.

Example fix

// before
result = pipeline.run({})
# after
result = pipeline.run({"retriever": {"query": "What is Haystack?"}})

Defensive patterns

Strategy: validation

Validate before calling

for name, comp in pipeline.components.items():
    for sock_name, sock in comp.__haystack_input__._sockets_dict.items():
        if sock.senders == [] and sock.is_mandatory and sock_name not in data.get(name, {}):
            raise ValueError(f"Must supply {name}.{sock_name}")

Type guard

def has_all_mandatory(name: str, data: dict) -> bool:
    comp = pipeline.get_component(name)
    return all(s in data.get(name, {}) for s, sock in comp.__haystack_input__._sockets_dict.items()
               if sock.senders == [] and sock.is_mandatory)

Try / catch

try:
    result = pipeline.run(data)
except ValueError as e:
    logger.error("Missing mandatory input: %s", e)

Prevention

List all unconnected mandatory sockets before calling run()
Always supply inputs for entry-point components of the pipeline
Use pipeline.connect() instead of relying on run-time inputs where possible

When it happens

Trigger: Calling pipeline.run() with an empty or partial dict while the pipeline contains a component whose mandatory socket has zero senders; e.g. a retriever with no connected query input and run({}) or run({"other_component": {...}}).

Common situations: Forgetting to pass the prompt/question to the first component of a linear pipeline; building a pipeline where one component was disconnected during refactoring; pipelines assembled conditionally where a required input path was left unconnected.

Related errors

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