deepset-ai/haystack · error · DeserializationError

Class '{serialized_component['type']}' not correctly importe

Error message

Class '{serialized_component['type']}' not correctly imported

What it means

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.

Source

Thrown at haystack/utils/deserialization.py:54

    :raises DeserializationError:
        If the key is missing in the serialized data, the value is not a dictionary,
        the type key is missing, the class cannot be imported, or the class lacks a 'from_dict' method.
    """
    if key not in data:
        raise DeserializationError(f"Missing '{key}' in serialization data")

    serialized_component = data[key]

    if not isinstance(serialized_component, dict):
        raise DeserializationError(f"The value of '{key}' is not a dictionary")

    if "type" not in serialized_component:
        raise DeserializationError(f"Missing 'type' in {key} serialization data")

    try:
        component_class = import_class_by_name(serialized_component["type"])
    except ImportError as e:
        raise DeserializationError(f"Class '{serialized_component['type']}' not correctly imported") from e

    data[key] = component_from_dict(cls=component_class, data=serialized_component, name=key)

View on GitHub (pinned to e318778c9b)

Solutions

1. pip install the package providing the class named in 'type' (e.g. an integration package)
2. Check the 'type' string for typos and confirm it matches the current class path (classes may have moved between releases)
3. Pin/align the haystack and integration versions between the environment that serialized and the one deserializing
4. Import the class manually (python -c 'from ... import ...') to confirm the exact ImportError

Example fix

// before (type references uninstalled integration)
"type": "haystack_integrations.components.generators.google.genai.GeminiGenerator"
// after
pip install google-genai-haystack
# then retry loads(); keep the type string as-is

def class_importable(type_path: str) -> bool:
    try:
        from haystack.core.serialization import import_class_by_name
        import_class_by_name(type_path)
        return True
    except ImportError:
        return False
# check each component's 'type' in the serialized data before loading

def is_known_component_type(v: dict) -> bool:
    t = v.get("type")
    return isinstance(t, str) and class_importable(t)

from haystack.core.errors import DeserializationError
try:
    pipe = Pipeline.loads(yaml_str)
except DeserializationError as e:
    print(f"Cannot import component class: {e}. Install the required integration package.")

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Could not import '{callable_handle}' as a module or callable
• Refusing to deserialize an OutputAdapter with unsafe=True wh
• Refusing to deserialize an OutputAdapter with custom filters
• Refusing to deserialize a ConditionalRouter with unsafe=True
• Refusing to deserialize a ConditionalRouter with custom filt

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