deepset-ai/haystack · error · InvalidMappingValueError

Invalid path format: '{path}'. Expected 'component_name.sock

Error message

Invalid path format: '{path}'. Expected 'component_name.socket_name'.

What it means

Mapping paths in SuperComponent must be 'component_name.socket_name' strings. _split_component_path uses parse_connect_string and raises InvalidMappingValueError when no socket part is present.

Source

Thrown at haystack/core/super_component/super_component.py:179

        filtered_inputs = {param: value for param, value in kwargs.items() if value is not _delegate_default}
        pipeline_inputs = self._map_explicit_inputs(input_mapping=self.input_mapping, inputs=filtered_inputs)
        pipeline_outputs = await self.pipeline.run_async(data=pipeline_inputs)
        return self._map_explicit_outputs(pipeline_outputs, self.output_mapping)

    @staticmethod
    def _split_component_path(path: str) -> tuple[str, str]:
        """
        Splits a component path into a component name and a socket name.

        :param path: A string in the format "component_name.socket_name".
        :returns:
            A tuple containing (component_name, socket_name).
        :raises InvalidMappingValueError:
            If the path format is incorrect.
        """
        comp_name, socket_name = parse_connect_string(path)
        if socket_name is None:
            raise InvalidMappingValueError(f"Invalid path format: '{path}'. Expected 'component_name.socket_name'.")
        return comp_name, socket_name

    def _validate_input_mapping(
        self, pipeline_inputs: dict[str, dict[str, Any]], input_mapping: dict[str, list[str]]
    ) -> None:
        """
        Validates the input mapping to ensure that specified components and sockets exist in the pipeline.

        :param pipeline_inputs: A dictionary containing pipeline input specifications.
        :param input_mapping: A dictionary mapping wrapper input names to pipeline socket paths.
        :raises InvalidMappingTypeError:
            If the input mapping is of invalid type or contains invalid types.
        :raises InvalidMappingValueError:
            If the input mapping contains nonexistent components or sockets.
        """
        if not isinstance(input_mapping, dict):
            raise InvalidMappingTypeError("input_mapping must be a dictionary")

View on GitHub (pinned to e318778c9b)

Solutions

1. Use the full 'component_name.socket_name' format in every mapping path
2. Verify the socket name exists on that component

Example fix

// before
input_mapping = {"text": ["my_embedder"]}
// after
input_mapping = {"text": ["my_embedder.text"]}

def validate_paths(mapping: dict) -> None:
    for paths in mapping.values():
        for p in (paths if isinstance(paths, list) else [paths]):
            if not isinstance(p, str) or "." not in p:
                raise ValueError(f"Path '{p}' must be 'component_name.socket_name'")

def is_valid_path(p: object) -> bool:
    return isinstance(p, str) and p.count(".") == 1 and all(part for part in p.split("."))

from haystack.core.errors import InvalidMappingValueError
try:
    super_comp = SuperComponent(pipeline=pipe, input_mapping=mapping)
except InvalidMappingValueError as e:
    if "Invalid path format" in str(e):
        print("Fix to 'component.socket':", e)
    else:
        raise

When it happens

Trigger: Passing an input_mapping or output_mapping path without a dot, e.g. 'my_component' instead of 'my_component.input', or a path with multiple dots/malformed syntax that yields socket_name None.

Common situations: Listing just the component name in a mapping; copy-pasted keys missing the socket suffix; using a socket name containing characters that break the connect-string parser.

Related errors

• Pipeline must be provided to SuperComponent.
• input_mapping must be a dictionary
• Input paths for '{wrapper_input_name}' must be a list of str
• Component '{comp_name}' not found in pipeline inputs. Availa
• Input socket '{socket_name}' not found in component '{comp_n

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