FoundationAgents/MetaGPT · error · ValueError

Missing __module_class_name field

Error message

Missing __module_class_name field

What it means

MetaGPT's polymorphic serialization base (metagpt/base/base_serialization.py) deserializes objects by reading the __module_class_name marker from the serialized dict to pick the right subclass. If that field is absent while the target class is a polymorphic base (or the class does not match), ValidationError/ValueError 'Missing __module_class_name field' is raised because there is no way to know which concrete subclass to instantiate.

Source

Thrown at metagpt/base/base_serialization.py:54

        # it is a dict so make sure to remove the __module_class_name
        # because we don't allow extra keywords but want to ensure
        # e.g Cat.model_validate(cat.model_dump()) works
        class_full_name = value.pop("__module_class_name", None)

        # if it's not the polymorphic base we construct via default handler
        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

1. Serialize with the framework's own serializer so __module_class_name is included, and do not strip underscore keys before deserialization.
2. If you must patch a dict, re-add the marker: value['__module_class_name'] = 'metagpt.module.ClassName' before deserializing.
3. Deserialize against the concrete subclass directly (class_type(**value)) when you know the type, bypassing the polymorphic path.

Example fix

# before
d = json.loads(saved_json)          # __module_class_name lost
obj = MyClass.serialization_module_from_dict(d)  # ValueError

# after
d = json.loads(saved_json)
d.setdefault('__module_class_name', 'metagpt.module.MyClass')
obj = MyClass.serialization_module_from_dict(d)

if isinstance(value, dict) and '__module_class_name' not in value:
    value['__module_class_name'] = f'{cls.__module__}.{cls.__qualname__}'
obj = cls.serialization_module_from_dict(value)

def has_class_marker(d: dict) -> bool:
    return isinstance(d, dict) and isinstance(d.get('__module_class_name'), str) and d['__module_class_name']

try:
    obj = cls.serialization_module_from_dict(value)
except ValueError:
    value = dict(value)
    value['__module_class_name'] = 'metagpt.module.ExpectedClass'
    obj = cls.serialization_module_from_dict(value)

When it happens

Trigger: Calling BaseModel.serialization_module_from_dict (or APIs that use it, e.g. context/agent deserialization) on a dict that was produced by plain json.loads of stored JSON where __module_class_name was stripped, or by manually constructing a dict of field values without the marker.

Common situations: Persisting serialized objects after post-processing that removes underscore-prefixed keys; schema drift between MetaGPT versions that renamed the marker field; hand-crafted dicts passed to deserializing loaders.

Related errors

• missing required key to init Message.instruct_content from d
• Trying to instantiate {class_full_name}, which has not yet b
• Field '{self.field_name}' not found in object: {obj_dict}
• recover storage meta file `team.json` not exist, not to reco

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