{"record":{"id":"72dcb8ef3a6ac914","repo":"deepset-ai/haystack","slug":"class-serialized-component-type-not-correct","errorCode":null,"errorMessage":"Class '{serialized_component['type']}' not correctly imported","messagePattern":"Class '(.+?)' not correctly imported","errorType":"exception","errorClass":"DeserializationError","httpStatus":null,"severity":"error","filePath":"haystack/utils/deserialization.py","lineNumber":54,"sourceCode":"    :raises DeserializationError:\n        If the key is missing in the serialized data, the value is not a dictionary,\n        the type key is missing, the class cannot be imported, or the class lacks a 'from_dict' method.\n    \"\"\"\n    if key not in data:\n        raise DeserializationError(f\"Missing '{key}' in serialization data\")\n\n    serialized_component = data[key]\n\n    if not isinstance(serialized_component, dict):\n        raise DeserializationError(f\"The value of '{key}' is not a dictionary\")\n\n    if \"type\" not in serialized_component:\n        raise DeserializationError(f\"Missing 'type' in {key} serialization data\")\n\n    try:\n        component_class = import_class_by_name(serialized_component[\"type\"])\n    except ImportError as e:\n        raise DeserializationError(f\"Class '{serialized_component['type']}' not correctly imported\") from e\n\n    data[key] = component_from_dict(cls=component_class, data=serialized_component, name=key)\n","sourceCodeStart":36,"sourceCodeEnd":57,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/utils/deserialization.py#L36-L57","documentation":"Raised by deserialize_component_inplace when the 'type' field in the serialized data names a class that cannot be imported (ImportError). The fully-qualified path in 'type' must resolve via import_class_by_name in the current environment.","triggerScenarios":"Deserializing a pipeline whose 'type' references a module not installed (e.g. a Haystack integration package like haystack-pycloud or unstructured), a renamed/moved class after a version upgrade, a typo'd class path, or serialized data moved between Python environments where the dependency is absent.","commonSituations":"Loading a colleague's pipeline YAML without installing the same integrations; upgrading Haystack or an integration so the class was renamed/moved; data serialized in a venv with extra packages and loaded in a plain venv.","solutions":["pip install the package providing the class named in 'type' (e.g. an integration package)","Check the 'type' string for typos and confirm it matches the current class path (classes may have moved between releases)","Pin/align the haystack and integration versions between the environment that serialized and the one deserializing","Import the class manually (python -c 'from ... import ...') to confirm the exact ImportError"],"exampleFix":"// before (type references uninstalled integration)\n\"type\": \"haystack_integrations.components.generators.google.genai.GeminiGenerator\"\n// after\npip install google-genai-haystack\n# then retry loads(); keep the type string as-is","handlingStrategy":"try-catch","validationCode":"def class_importable(type_path: str) -> bool:\n    try:\n        from haystack.core.serialization import import_class_by_name\n        import_class_by_name(type_path)\n        return True\n    except ImportError:\n        return False\n# check each component's 'type' in the serialized data before loading","typeGuard":"def is_known_component_type(v: dict) -> bool:\n    t = v.get(\"type\")\n    return isinstance(t, str) and class_importable(t)","tryCatchPattern":"from haystack.core.errors import DeserializationError\ntry:\n    pipe = Pipeline.loads(yaml_str)\nexcept DeserializationError as e:\n    print(f\"Cannot import component class: {e}. Install the required integration package.\")","preventionTips":["pip install all integration packages used by the pipeline (and pin versions)","Align haystack + integration versions between serialize and deserialize environments","Smoke-test loads() in CI in the deployment environment"],"tags":["deserialization","import","dependency","class-not-found"],"backgroundTag":"import-error-missing-dependency","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}