{"record":{"id":"c1d921e00bdeefaa","repo":"deepset-ai/haystack","slug":"failed-to-deserialize-data-payload-into-pydant","errorCode":null,"errorMessage":"Failed to deserialize data '{payload}' into Pydantic model '{value_type}'","messagePattern":"Failed to deserialize data '(.+?)' into Pydantic model '(.+?)'","errorType":"exception","errorClass":"DeserializationError","httpStatus":null,"severity":"error","filePath":"haystack/utils/base_serialization.py","lineNumber":319,"sourceCode":"    payload = value[\"data\"]\n\n    # Custom class where value_type is a qualified class name\n    # ValueError covers type names without a module prefix, which import_class_by_name cannot split\n    try:\n        cls = import_class_by_name(value_type)\n    except (ImportError, ValueError) as e:\n        raise DeserializationError(f\"Class '{value_type}' not correctly imported\") from e\n\n    # try from_dict (e.g. Haystack dataclasses and Components)\n    if hasattr(cls, \"from_dict\") and callable(cls.from_dict):\n        return cls.from_dict(payload)\n\n    # handle pydantic models\n    if issubclass(cls, pydantic.BaseModel):\n        try:\n            return cls.model_validate(payload)\n        except Exception as e:\n            raise DeserializationError(\n                f\"Failed to deserialize data '{payload}' into Pydantic model '{value_type}'\"\n            ) from e\n\n    # handle enum types\n    if issubclass(cls, Enum):\n        try:\n            return cls[payload]\n        except Exception as e:\n            raise DeserializationError(f\"Value '{payload}' is not a valid member of Enum '{value_type}'\") from e\n\n    # fallback: set attributes on a blank instance\n    deserialized_payload = {k: _deserialize_value(v) for k, v in payload.items()}\n    instance = cls.__new__(cls)\n    for attr_name, attr_value in deserialized_payload.items():\n        setattr(instance, attr_name, attr_value)\n    return instance\n","sourceCodeStart":301,"sourceCodeEnd":336,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/utils/base_serialization.py#L301-L336","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\n{\"model\": {\"name\": 123}}\n// after\n{\"model\": {\"name\": \"gpt-4\"}}  # field type corrected to match the Pydantic model","handlingStrategy":"try-catch","validationCode":"from haystack.utils import DeserializationError\nimport pydantic\n\ndef validate_payload(payload, model):\n    try:\n        model.model_validate(payload)\n    except pydantic.ValidationError as e:\n        raise ValueError(f\"payload invalid for {model.__name__}: {e}\")","typeGuard":"def is_pydantic_model(cls) -> bool:\n    return isinstance(cls, type) and issubclass(cls, pydantic.BaseModel)","tryCatchPattern":"try:\n    pipeline = Pipeline.loads(yaml_str)\nexcept DeserializationError as e:\n    logger.error(\"deserialization failed: %s; cause: %s\", e, e.__cause__)\n    raise","preventionTips":["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"],"tags":["python","pydantic","deserialization","haystack"],"backgroundTag":"pydantic-validation-failed","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}