{"record":{"id":"3c6b042296a0e6e0","repo":"deepset-ai/haystack","slug":"could-not-import-type-str-as-it-may-not-exist","errorCode":null,"errorMessage":"Could not import '{type_str}' as it may not exist or is not a valid class","messagePattern":"Could not import '(.+?)' as it may not exist or is not a valid class","errorType":"exception","errorClass":"DeserializationError","httpStatus":null,"severity":"error","filePath":"haystack/utils/type_serialization.py","lineNumber":269,"sourceCode":"        # arguments.\n        if main_type is typing.Literal:\n            return typing.Literal[ast.literal_eval(f\"({generics_str},)\")]\n\n        generic_args = [_deserialize_type_arg(arg) for arg in _parse_generic_args(generics_str)]\n\n        # Reconstruct\n        try:\n            return main_type[tuple(generic_args) if len(generic_args) > 1 else generic_args[0]]\n        except (TypeError, AttributeError) as e:\n            raise DeserializationError(f\"Could not apply arguments {generic_args} to type {main_type}\") from e\n\n    # Handle non-generic types\n    # First, check if there's a module prefix\n    if \".\" in type_str:\n        try:\n            return _import_class_by_name(type_str)\n        except ImportError as e:\n            raise DeserializationError(str(e)) from e\n\n    # No module prefix, check builtins and typing.\n    # (None / NoneType / Ellipsis are handled at the top of this function, before they can reach the\n    # builtin type gate below which would refuse them for not being types.)\n    if hasattr(builtins, type_str):\n        resolved = getattr(builtins, type_str)\n        # This bare-name path never consults the allowlist. A type annotation must resolve to an\n        # actual type, so builtin functions like `eval`/`exec` are rejected while types pass.\n        _check_builtin_is_type(resolved, type_str)\n        return resolved\n\n    # Then check typing\n    if hasattr(typing, type_str):\n        return getattr(typing, type_str)\n\n    raise DeserializationError(f\"Could not deserialize type: {type_str}\")\n\n","sourceCodeStart":251,"sourceCodeEnd":287,"githubUrl":"https://github.com/deepset-ai/haystack/blob/e318778c9bf60a1963e3b5f451359655dd696c30/haystack/utils/type_serialization.py#L251-L287","documentation":"Actually raised inside _import_class_by_name's guard chain (the SOURCE shown is the except clause in deserialize_type): when importing a dotted type path fails, _import_class_by_name raises ImportError('Could not import ...'), but in this code path the failure is reported as 'Could not import \\'{type_str}\\' as it may not exist or is not a valid class'. It indicates the serialized dotted type could not be resolved to an importable class in this environment.","triggerScenarios":"deserialize_type('some.module.SomeClass') where the module is absent, the class name changed, or the resolved attribute is not a class (fails the class-validity check); loading pipelines serialized against different code.","commonSituations":"Missing optional dependencies; refactor/renames between haystack versions; sharing serialized pipeline YAML across projects with different component packages.","solutions":["Install the missing package or fix the environment so the dotted path imports","Update the serialized type string to the current class path","Manually run `import some.module; some.module.SomeClass` to see the true cause","Check the accompanying logger.exception traceback for the underlying ImportError/AttributeError"],"exampleFix":"// before\ndeserialize_type(\"haystack.nodes.retriever.dense.DensePassageRetriever\")  # 1.x path\n// after\ndeserialize_type(\"haystack.components.retrievers.in_memory.InMemoryEmbeddingRetriever\")  # 2.x path","handlingStrategy":"try-catch","validationCode":"import importlib\ndef dotted_importable(path):\n    try:\n        importlib.import_module(path.rsplit(\".\", 1)[0])\n        return True\n    except ImportError:\n        return False","typeGuard":null,"tryCatchPattern":"from haystack.utils import DeserializationError\ntry:\n    t = deserialize_type(type_str)\nexcept DeserializationError:\n    t = None  # fall back or re-serialize with current library","preventionTips":["Re-serialize pipelines after any haystack upgrade","Keep a mapping of legacy type paths to current ones","Log and inspect the underlying ImportError for root cause"],"tags":["python","deserialization","import-error","haystack"],"backgroundTag":"module-import-failed","analyzedSha":"e318778c9bf60a1963e3b5f451359655dd696c30","analyzedAt":"2026-08-30T11:45:20.711Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}