deepset-ai/haystack · error · DeserializationError

Failed to deserialize data '{payload}' into Pydantic model '

Error message

Failed to deserialize data '{payload}' into Pydantic model '{value_type}'

What it means

Haystack raised DeserializationError because a serialized payload could not be validated into the target Pydantic model via cls.model_validate(payload). This wraps the underlying pydantic.ValidationError so the original failure (wrong fields, bad types) is attached as __cause__. It occurs in _deserialize_value when restoring a Pydantic model stored in component init parameters.

Source

Thrown at haystack/utils/base_serialization.py:319

    payload = value["data"]

    # Custom class where value_type is a qualified class name
    # ValueError covers type names without a module prefix, which import_class_by_name cannot split
    try:
        cls = import_class_by_name(value_type)
    except (ImportError, ValueError) as e:
        raise DeserializationError(f"Class '{value_type}' not correctly imported") from e

    # try from_dict (e.g. Haystack dataclasses and Components)
    if hasattr(cls, "from_dict") and callable(cls.from_dict):
        return cls.from_dict(payload)

    # handle pydantic models
    if issubclass(cls, pydantic.BaseModel):
        try:
            return cls.model_validate(payload)
        except Exception as e:
            raise DeserializationError(
                f"Failed to deserialize data '{payload}' into Pydantic model '{value_type}'"
            ) from e

    # handle enum types
    if issubclass(cls, Enum):
        try:
            return cls[payload]
        except Exception as e:
            raise DeserializationError(f"Value '{payload}' is not a valid member of Enum '{value_type}'") from e

    # fallback: set attributes on a blank instance
    deserialized_payload = {k: _deserialize_value(v) for k, v in payload.items()}
    instance = cls.__new__(cls)
    for attr_name, attr_value in deserialized_payload.items():
        setattr(instance, attr_name, attr_value)
    return instance

View on GitHub (pinned to e318778c9b)

Solutions

Print the __cause__ (the pydantic.ValidationError) to see the exact failing field and fix the payload
Update the serialized data (YAML/JSON) to match the current model schema
Pin or upgrade the library version that defines the Pydantic model so schemas match
Use model_construct or adjust model validators if intentionally lenient parsing is needed

Example fix

// before
{"model": {"name": 123}}
// after
{"model": {"name": "gpt-4"}}  # field type corrected to match the Pydantic model

Defensive patterns

Strategy: try-catch

Validate before calling

from haystack.utils import DeserializationError
import pydantic

def validate_payload(payload, model):
    try:
        model.model_validate(payload)
    except pydantic.ValidationError as e:
        raise ValueError(f"payload invalid for {model.__name__}: {e}")

Type guard

def is_pydantic_model(cls) -> bool:
    return isinstance(cls, type) and issubclass(cls, pydantic.BaseModel)

Try / catch

try:
    pipeline = Pipeline.loads(yaml_str)
except DeserializationError as e:
    logger.error("deserialization failed: %s; cause: %s", e, e.__cause__)
    raise

Prevention

Regenerate serialized pipelines after upgrading any library that defines Pydantic models in component params
Never hand-edit model payloads; use pipeline.dumps() output as the base
Log e.__cause__ (pydantic.ValidationError) for the exact field error
Add unit tests that dumps->loads round-trip every custom component

When it happens

Trigger: Calling Pipeline.dumps/loads or component from_dict where an init parameter is a Pydantic model and the serialized dict no longer matches the model schema: missing required field, extra/renamed field, or wrong value type.

Common situations: Pipeline YAML edited by hand; pipeline serialized with an older version of a component whose Pydantic model schema changed; passing a plain dict instead of a model-compatible payload after a library upgrade.

Related errors

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