deepset-ai/haystack · error · InvalidMappingTypeError

input_mapping must be a dictionary

Error message

input_mapping must be a dictionary

What it means

input_mapping must be a dict mapping wrapper input names to lists of pipeline paths. Passing any other type raises InvalidMappingTypeError.

Source

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

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

        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(

View on GitHub (pinned to e318778c9b)

Solutions

  1. Wrap the mapping in a dict: {"wrapper_input": ["component.socket"]}
  2. Fix config loading so the JSON/YAML section is parsed as an object, not an array

Example fix

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

Strategy: validation

Validate before calling

def ensure_input_mapping_shape(input_mapping):
    if not isinstance(input_mapping, dict):
        raise TypeError("input_mapping must be a dict of {name: ["component.socket", ...]}")
    return input_mapping

Type guard

from typing import Any
def is_valid_input_mapping(v: Any) -> bool:
    return isinstance(v, dict) and all(isinstance(k, str) and isinstance(l, list) for k, l in v.items())

Try / catch

from haystack.core.errors import InvalidMappingTypeError
try:
    super_comp = SuperComponent(pipeline=pipe, input_mapping=input_mapping)
except InvalidMappingTypeError as e:
    if str(e) == "input_mapping must be a dictionary":
        input_mapping = dict(input_mapping)  # e.g. from list of pairs
        super_comp = SuperComponent(pipeline=pipe, input_mapping=input_mapping)
    else:
        raise

Prevention

When it happens

Trigger: SuperComponent(pipeline=..., input_mapping=[...]) or input_mapping=None-as-list/set/string instead of a dict.

Common situations: Passing a list of tuples instead of a dict; JSON config decoded into the wrong shape; forgetting input_mapping entirely while passing it positionally wrong.

Related errors

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