What causes "Output names in output_mapping must be strings." in deepset-ai/haystack?

Use a plain string for each wrapper output name: {"component.socket": "docs"}

deepset-ai/haystack · error · InvalidMappingTypeError

Output names in output_mapping must be strings.

Error message

Output names in output_mapping must be strings.

What it means

In output_mapping, values are the wrapper's output names and must be strings. A non-string value (int, list, None) raises InvalidMappingTypeError.

Source

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

                input_mapping[socket_name].append(f"{comp_name}.{socket_name}")
        return input_mapping

    def _validate_output_mapping(
        self, pipeline_outputs: dict[str, dict[str, Any]], output_mapping: dict[str, str]
    ) -> None:
        """
        Validates the output mapping to ensure that specified components and sockets exist in the pipeline.

        :param pipeline_outputs: A dictionary containing pipeline output specifications.
        :param output_mapping: A dictionary mapping pipeline socket paths to wrapper output names.
        :raises InvalidMappingTypeError:
            If the output mapping is of invalid type or contains invalid types.
        :raises InvalidMappingValueError:
            If the output mapping contains nonexistent components or sockets.
        """
        for pipeline_output_path, wrapper_output_name in output_mapping.items():
            if not isinstance(wrapper_output_name, str):
                raise InvalidMappingTypeError("Output names in output_mapping must be strings.")
            comp_name, socket_name = self._split_component_path(pipeline_output_path)
            if comp_name not in pipeline_outputs:
                raise InvalidMappingValueError(f"Component '{comp_name}' not found among pipeline outputs.")
            if socket_name not in pipeline_outputs[comp_name]:
                raise InvalidMappingValueError(f"Output socket '{socket_name}' not found in component '{comp_name}'.")

    def _resolve_output_types_from_mapping(
        self, pipeline_outputs: dict[str, dict[str, Any]], output_mapping: dict[str, str]
    ) -> dict[str, Any]:
        """
        Resolves and validates output types based on the provided output mapping.

        This function ensures that all mapped pipeline outputs are correctly assigned to
        the corresponding SuperComponent outputs while preventing duplicate output names.

        :param pipeline_outputs: A dictionary containing pipeline output specifications.
        :param output_mapping: A dictionary mapping pipeline output socket paths to SuperComponent output names.
        :returns:

View on GitHub (pinned to e318778c9b)

Solutions

Use a plain string for each wrapper output name: {"component.socket": "docs"}

Example fix

// before
output_mapping = {"retriever.documents": ["docs"]}
// after
output_mapping = {"retriever.documents": "docs"}

Defensive patterns

Strategy: validation

Validate before calling

def ensure_output_names_str(output_mapping):
    for path, name in output_mapping.items():
        if not isinstance(name, str):
            raise TypeError(f"output name for '{path}' must be a string, got {type(name).__name__}")

Type guard

def is_valid_output_mapping(v: object) -> bool:
    return isinstance(v, dict) and all(isinstance(name, str) for name in v.values())

Try / catch

from haystack.core.errors import InvalidMappingTypeError
try:
    super_comp = SuperComponent(pipeline=pipe, output_mapping=output_mapping)
except InvalidMappingTypeError as e:
    if "must be strings" in str(e):
        output_mapping = {k: v[0] if isinstance(v, list) and v else str(v) for k, v in output_mapping.items()}
        super_comp = SuperComponent(pipeline=pipe, output_mapping=output_mapping)
    else:
        raise

Prevention

Values in output_mapping are output names: plain strings only
Do not reuse input_mapping list-style values for output_mapping
Validate mapping config shapes before constructing SuperComponent

When it happens

Trigger: output_mapping = {"retriever.documents": 1} or {"retriever.documents": ["docs"]}.

Common situations: Copying input_mapping-style list values into output_mapping; programmatic construction with non-string keys/values; config typos.

Related errors

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