FoundationAgents/MetaGPT · error · TypeError

Trying to instantiate {class_full_name}, which has not yet b

Error message

Trying to instantiate {class_full_name}, which has not yet been defined!

What it means

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.

Source

Thrown at metagpt/base/base_serialization.py:60

        if not cls.__is_polymorphic_base:
            if class_full_name is None:
                return handler(value)
            elif str(cls) == f"<class '{class_full_name}'>":
                return handler(value)
            else:
                # f"Trying to instantiate {class_full_name} but this is not the polymorphic base class")
                pass

        # otherwise we lookup the correct polymorphic type and construct that
        # instead
        if class_full_name is None:
            raise ValueError("Missing __module_class_name field")

        class_type = cls.__subclasses_map__.get(class_full_name, None)

        if class_type is None:
            # TODO could try dynamic import
            raise TypeError(f"Trying to instantiate {class_full_name}, which has not yet been defined!")

        return class_type(**value)

    def __init_subclass__(cls, is_polymorphic_base: bool = False, **kwargs):
        cls.__is_polymorphic_base = is_polymorphic_base
        cls.__subclasses_map__[f"{cls.__module__}.{cls.__qualname__}"] = cls
        super().__init_subclass__(**kwargs)

View on GitHub (pinned to 11cdf466d0)

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.

Example fix

# before
obj = BaseCls.serialization_module_from_dict(d)  # TypeError: my_plugin.actions.MyAction not defined

# after
import importlib
importlib.import_module('my_plugin.actions')   # registers subclass in __subclasses_map__
obj = BaseCls.serialization_module_from_dict(d)

Defensive patterns

Strategy: fallback

Validate before calling

mod_name, _, _ = class_full_name.rpartition('.')
try:
    importlib.import_module(mod_name)
except ImportError:
    raise ImportError(f'Cannot load class {class_full_name}; install/import its module first')

Type guard

def class_registered(base_cls, full_name: str) -> bool:
    return full_name in base_cls.__subclasses_map__

Try / catch

try:
    obj = BaseCls.serialization_module_from_dict(value)
except TypeError:
    importlib.import_module(value['__module_class_name'].rsplit('.', 1)[0])
    obj = BaseCls.serialization_module_from_dict(value)

Prevention

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.

When it happens

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

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

Related errors

AI-assisted analysis of FoundationAgents/MetaGPT@11cdf466d0 (2026-08-14). Data as JSON: /api/errors/e951cb6d01d13702. Report an issue: GitHub.