deepset-ai/haystack · error · SerializationError

Component '{name}' of type '{type(component).name}' has

Error message

Component '{name}' of type '{type(component).__name__}' has an unsupported value of type '{type(v).__name__}' in the serialized data.

What it means

Haystack validates that a component's serialized output contains only JSON-safe primitive types (str, int, float, bool, list, dict, set, tuple, None) at every nesting level. This error is raised when a value inside a serialized structure (including nested lists) is of an unsupported type, such as a custom object, datetime, or bytes. It guards against silently producing data that cannot round-trip through JSON.

Source

Thrown at haystack/core/serialization.py:100

                # In case the init parameter was not assigned, we use the default value
                param_value = param.default
            init_parameters[param_name] = param_value

        data = default_to_dict(obj, **init_parameters)

    _validate_component_to_dict_output(obj, name, data)
    return data


def _validate_component_to_dict_output(component: Any, name: str, data: dict[str, Any]) -> None:
    # Ensure that only basic Python types are used in the serde data.
    def is_allowed_type(obj: Any) -> bool:
        return isinstance(obj, (str, int, float, bool, list, dict, set, tuple, type(None)))

    def check_iterable(iterable: Iterable[Any]) -> None:
        for v in iterable:
            if not is_allowed_type(v):
                raise SerializationError(
                    f"Component '{name}' of type '{type(component).__name__}' has an unsupported value "
                    f"of type '{type(v).__name__}' in the serialized data."
                )
            if isinstance(v, (list, set, tuple)):
                check_iterable(v)
            elif isinstance(v, dict):
                check_dict(v)

    def check_dict(d: dict[str, Any]) -> None:
        if any(not isinstance(k, str) for k in d):
            raise SerializationError(
                f"Component '{name}' of type '{type(component).__name__}' has a non-string key in the serialized data."
            )

        for k, v in d.items():
            if not is_allowed_type(v):
                raise SerializationError(
                    f"Component '{name}' of type '{type(component).__name__}' has an unsupported value "

View on GitHub (pinned to e318778c9b)

Solutions

Fix the component's to_dict() to serialize the offending value (e.g. convert datetime to ISO string, bytes to base64).
Convert the init parameter to a supported type before passing it to the component constructor.
Implement from_dict/to_dict pair that converts custom objects to dicts with a 'type' key so they deserialize correctly.
As a last resort wrap the value in a supported container only if the value is genuinely serializable; do not bypass validation.

Example fix

// before
class MyComp(Component):
    def to_dict(self):
        return {"type": ..., "init_parameters": {"start": self.start}}  # start is a datetime

// after
class MyComp(Component):
    def to_dict(self):
        return {"type": ..., "init_parameters": {"start": self.start.isoformat()}}

Defensive patterns

Strategy: validation

Validate before calling

def validate_serializable(value, _depth=0):
    if _depth > 32:
        raise ValueError("structure too deep")
    allowed = (str, int, float, bool, list, dict, set, tuple, type(None))
    if not isinstance(value, allowed):
        raise ValueError(f"unsupported type {type(value).__name__}")
    if isinstance(value, (list, set, tuple)):
        for v in value: validate_serializable(v, _depth + 1)
    elif isinstance(value, dict):
        for k, v in value.items():
            if not isinstance(k, str): raise ValueError("non-string key")
            validate_serializable(v, _depth + 1)
    return True

Type guard

def is_serializable_value(v) -> bool:
    return isinstance(v, (str, int, float, bool, list, dict, set, tuple, type(None)))

Try / catch

from haystack.core.errors import SerializationError
try:
    yaml_str = pipeline.dumps()
except SerializationError as e:
    # parse the reported component and value type from e, fix its to_dict
    print("Fix component serialization:", e)

Prevention

Always pair custom Component to_dict with from_dict converting all init parameters to JSON-safe types
Never pass raw objects (datetime, bytes, numpy) as component init parameters
Run pipeline.dumps() in CI on every pipeline definition to catch serialization issues early
Prefer str/enum .value representations for non-primitive fields

When it happens

Trigger: Calling pipeline.dumps()/to_dict() when a component's to_dict() emits an unsupported object, e.g. a datetime, bytes, path object, or a custom class instance inside an init_parameters list, or a default_ color/context object leaked into serialized data.

Common situations: Custom components whose to_dict() passes through raw init parameters without converting them; third-party components that changed their serialized format; passing non-JSON values like numpy scalars or enum objects as pipeline component init args.

Related errors

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