{"record":{"id":"e951cb6d01d13702","repo":"FoundationAgents/MetaGPT","slug":"trying-to-instantiate-class-full-name-which-has","errorCode":null,"errorMessage":"Trying to instantiate {class_full_name}, which has not yet been defined!","messagePattern":"Trying to instantiate (.+?), which has not yet been defined!","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"metagpt/base/base_serialization.py","lineNumber":60,"sourceCode":"        if not cls.__is_polymorphic_base:\n            if class_full_name is None:\n                return handler(value)\n            elif str(cls) == f\"<class '{class_full_name}'>\":\n                return handler(value)\n            else:\n                # f\"Trying to instantiate {class_full_name} but this is not the polymorphic base class\")\n                pass\n\n        # otherwise we lookup the correct polymorphic type and construct that\n        # instead\n        if class_full_name is None:\n            raise ValueError(\"Missing __module_class_name field\")\n\n        class_type = cls.__subclasses_map__.get(class_full_name, None)\n\n        if class_type is None:\n            # TODO could try dynamic import\n            raise TypeError(f\"Trying to instantiate {class_full_name}, which has not yet been defined!\")\n\n        return class_type(**value)\n\n    def __init_subclass__(cls, is_polymorphic_base: bool = False, **kwargs):\n        cls.__is_polymorphic_base = is_polymorphic_base\n        cls.__subclasses_map__[f\"{cls.__module__}.{cls.__qualname__}\"] = cls\n        super().__init_subclass__(**kwargs)\n","sourceCodeStart":42,"sourceCodeEnd":68,"githubUrl":"https://github.com/FoundationAgents/MetaGPT/blob/11cdf466d042aece04fc6cfd13b28e1a70341b1f/metagpt/base/base_serialization.py#L42-L68","documentation":"The polymorphic deserializer looks up class_full_name in cls.__subclasses_map__, which is populated by __init_subclass__ for every subclass that has been imported. If the named class has never been imported into the process, the map lookup returns None and TypeError 'Trying to instantiate X, which has not yet been defined!' is raised — the class exists in the payload but not in the running Python session.","triggerScenarios":"Deserializing a payload referencing a custom subclass (e.g. 'my_plugin.actions.MyAction') without importing my_plugin.actions first; loading old serialized state whose classes moved to a new module in a newer MetaGPT version; deserializing in a fresh worker process that only imported the base module.","commonSituations":"Distributed jobs where the writer process had extra plugin modules imported but the reader does not; renaming/refactoring modules between releases; pickled/session state replayed against a different MetaGPT install.","solutions":["Import the module containing the subclass before deserializing (importlib.import_module('my_plugin.actions')).","Fix the module path in the serialized __module_class_name if the class moved in a newer version.","Register custom subclasses via __init_subclass__ simply by importing them at startup of your app."],"exampleFix":"# before\nobj = BaseCls.serialization_module_from_dict(d)  # TypeError: my_plugin.actions.MyAction not defined\n\n# after\nimport importlib\nimportlib.import_module('my_plugin.actions')   # registers subclass in __subclasses_map__\nobj = BaseCls.serialization_module_from_dict(d)","handlingStrategy":"fallback","validationCode":"mod_name, _, _ = class_full_name.rpartition('.')\ntry:\n    importlib.import_module(mod_name)\nexcept ImportError:\n    raise ImportError(f'Cannot load class {class_full_name}; install/import its module first')","typeGuard":"def class_registered(base_cls, full_name: str) -> bool:\n    return full_name in base_cls.__subclasses_map__","tryCatchPattern":"try:\n    obj = BaseCls.serialization_module_from_dict(value)\nexcept TypeError:\n    importlib.import_module(value['__module_class_name'].rsplit('.', 1)[0])\n    obj = BaseCls.serialization_module_from_dict(value)","preventionTips":["Import all custom subclass modules at application startup.","Keep serialized class paths in sync with refactors.","Run deserialization smoke tests in fresh processes to catch missing imports."],"tags":["serialization","dynamic-import","subclass-registry","versioning"],"backgroundTag":null,"analyzedSha":"11cdf466d042aece04fc6cfd13b28e1a70341b1f","analyzedAt":"2026-08-14T23:20:02.994Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}