{"record":{"id":"b129e98678a469a8","repo":"FoundationAgents/MetaGPT","slug":"missing-required-key-to-init-message-instruct-cont","errorCode":null,"errorMessage":"missing required key to init Message.instruct_content from dict","messagePattern":"missing required key to init Message\\.instruct_content from dict","errorType":"exception","errorClass":"KeyError","httpStatus":null,"severity":"error","filePath":"metagpt/schema.py","lineNumber":262,"sourceCode":"    @field_validator(\"id\", mode=\"before\")\n    @classmethod\n    def check_id(cls, id: str) -> str:\n        return id if id else uuid.uuid4().hex\n\n    @field_validator(\"instruct_content\", mode=\"before\")\n    @classmethod\n    def check_instruct_content(cls, ic: Any) -> BaseModel:\n        if ic and isinstance(ic, dict) and \"class\" in ic:\n            if \"mapping\" in ic:\n                # compatible with custom-defined ActionOutput\n                mapping = actionoutput_str_to_mapping(ic[\"mapping\"])\n                actionnode_class = import_class(\"ActionNode\", \"metagpt.actions.action_node\")  # avoid circular import\n                ic_obj = actionnode_class.create_model_class(class_name=ic[\"class\"], mapping=mapping)\n            elif \"module\" in ic:\n                # subclasses of BaseModel\n                ic_obj = import_class(ic[\"class\"], ic[\"module\"])\n            else:\n                raise KeyError(\"missing required key to init Message.instruct_content from dict\")\n            ic = ic_obj(**ic[\"value\"])\n        return ic\n\n    @field_validator(\"cause_by\", mode=\"before\")\n    @classmethod\n    def check_cause_by(cls, cause_by: Any) -> str:\n        return any_to_str(cause_by if cause_by else import_class(\"UserRequirement\", \"metagpt.actions.add_requirement\"))\n\n    @field_validator(\"sent_from\", mode=\"before\")\n    @classmethod\n    def check_sent_from(cls, sent_from: Any) -> str:\n        return any_to_str(sent_from if sent_from else \"\")\n\n    @field_validator(\"send_to\", mode=\"before\")\n    @classmethod\n    def check_send_to(cls, send_to: Any) -> set:\n        return any_to_str_set(send_to if send_to else {MESSAGE_ROUTE_TO_ALL})\n","sourceCodeStart":244,"sourceCodeEnd":280,"githubUrl":"https://github.com/FoundationAgents/MetaGPT/blob/11cdf466d042aece04fc6cfd13b28e1a70341b1f/metagpt/schema.py#L244-L280","documentation":"Message.check_instruct_content rehydrates instruct_content from a serialized dict. It accepts dicts with a \"class\" key plus either \"mapping\" (custom ActionNode models) or \"module\" (importable BaseModel subclasses). A dict carrying \"class\" but neither of those keys raises this KeyError, because there is no way to reconstruct the model class.","triggerScenarios":"Message(**dict_from_json) / Message.model_validate where the serialized instruct_content dict lost its \"mapping\" or \"module\" entry — e.g. hand-edited storage JSON, partial serialization, or a custom dict built with only class/value keys.","commonSituations":"Loading persisted team/workspace state where instruct_content was saved by an older MetaGPT version; manually crafting Message dicts for replay/testing; schema changes removing the module field.","solutions":["Regenerate the serialized message with the current MetaGPT version so mapping/module is included","Repair the stored dict to include \"module\" (importable path of the pydantic class) alongside \"class\" and \"value\"","If the instruct content is not needed, drop the malformed instruct_content key instead of passing a partial dict"],"exampleFix":"// before\nmsg = Message.model_validate({\"content\": \"x\", \"instruct_content\": {\"class\": \"InvoicePath\", \"value\": {...}}})  # KeyError\n\n// after\nmsg = Message.model_validate({\"content\": \"x\", \"instruct_content\": {\"class\": \"InvoicePath\", \"module\": \"metagpt.actions.invoice_ocr\", \"value\": {...}}})","handlingStrategy":"validation","validationCode":"ic = raw.get(\"instruct_content\")\nif isinstance(ic, dict):\n    assert \"class\" in ic, \"instruct_content dict needs 'class'\"\n    assert \"mapping\" in ic or \"module\" in ic, \"instruct_content dict needs 'mapping' or 'module' to rebuild the class\"","typeGuard":"def is_rehydratable_instruct_content(ic) -> bool:\n    if not isinstance(ic, dict):\n        return True  # non-dict passes through unchanged\n    return \"class\" in ic and (\"mapping\" in ic or \"module\" in ic)","tryCatchPattern":"try:\n    msg = Message.model_validate(data)\nexcept KeyError as e:\n    if \"missing required key\" in str(e):\n        data[\"instruct_content\"].setdefault(\"module\", \"metagpt.schema\")  # or drop the field\n        msg = Message.model_validate(data)\n    else:\n        raise","preventionTips":["Always serialize/deserialize Messages with the same MetaGPT version","When hand-building Message dicts, include class+module+value or class+mapping+value","Validate persisted JSON with a schema check before load"],"tags":["schema","serialization","message","deserialization"],"backgroundTag":null,"analyzedSha":"11cdf466d042aece04fc6cfd13b28e1a70341b1f","analyzedAt":"2026-08-14T23:20:02.994Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}