deepset-ai/haystack · error · InvalidMappingTypeError

Input paths for '{wrapper_input_name}' must be a list of str

Error message

Input paths for '{wrapper_input_name}' must be a list of strings.

What it means

Each value of input_mapping must be a list of 'component.socket' strings. A value of another type (string, dict, tuple) raises InvalidMappingTypeError.

Source

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

    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")

        for wrapper_input_name, pipeline_input_paths in input_mapping.items():
            if not isinstance(pipeline_input_paths, list):
                raise InvalidMappingTypeError(f"Input paths for '{wrapper_input_name}' must be a list of strings.")
            for path in pipeline_input_paths:
                comp_name, socket_name = self._split_component_path(path)
                if comp_name not in pipeline_inputs:
                    raise InvalidMappingValueError(
                        f"Component '{comp_name}' not found in pipeline inputs.\n"
                        f"Available components: {list(pipeline_inputs.keys())}"
                    )
                if socket_name not in pipeline_inputs[comp_name]:
                    raise InvalidMappingValueError(
                        f"Input socket '{socket_name}' not found in component '{comp_name}'.\n"
                        f"Available inputs for '{comp_name}': {list(pipeline_inputs[comp_name].keys())}"
                    )

    def _resolve_input_types_from_mapping(
        self, pipeline_inputs: dict[str, dict[str, Any]], input_mapping: dict[str, list[str]]
    ) -> dict[str, dict[str, Any]]:
        """
        Resolves and validates input types based on the provided input mapping.

View on GitHub (pinned to e318778c9b)

Solutions

  1. Always use a list for values, even for a single path: {"text": ["embedder.text"]}

Example fix

// before
input_mapping = {"text": "embedder.text"}
// after
input_mapping = {"text": ["embedder.text"]}
Defensive patterns

Strategy: validation

Validate before calling

def normalize_input_mapping(mapping: dict) -> dict:
    return {k: (v if isinstance(v, list) else [v]) for k, v in mapping.items()}

Type guard

def values_are_lists(mapping: dict) -> bool:
    return all(isinstance(v, list) and all(isinstance(p, str) for p in v) for v in mapping.values())

Try / catch

from haystack.core.errors import InvalidMappingTypeError
try:
    super_comp = SuperComponent(pipeline=pipe, input_mapping=input_mapping)
except InvalidMappingTypeError as e:
    if "must be a list of strings" in str(e):
        input_mapping = normalize_input_mapping(input_mapping)
        super_comp = SuperComponent(pipeline=pipe, input_mapping=input_mapping)
    else:
        raise

Prevention

When it happens

Trigger: input_mapping = {"text": "embedder.text"} (string instead of list) or {"text": ("embedder.text",)}.

Common situations: Forgetting the list brackets around a single path; mapping values copied from output_mapping-style dicts; config where one path is not wrapped in a list.

Related errors

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