{"record":{"id":"4edbab810dae801d","repo":"microsoft/autogen","slug":"unknown-message-type-message-type","errorCode":null,"errorMessage":"Unknown message type: {message_type}","messagePattern":"Unknown message type: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-agentchat/src/autogen_agentchat/messages.py","lineNumber":635,"sourceCode":"        \"\"\"Register a new message type with the factory.\"\"\"\n        if self.is_registered(message_type):\n            raise ValueError(f\"Message type {message_type} is already registered.\")\n        if not issubclass(message_type, BaseChatMessage) and not issubclass(message_type, BaseAgentEvent):\n            raise ValueError(f\"Message type {message_type} must be a subclass of BaseChatMessage or BaseAgentEvent.\")\n        # Get the class name of the\n        class_name = message_type.__name__\n        # Check if the class name is already registered.\n        # Register the message type.\n        self._message_types[class_name] = message_type\n\n    def create(self, data: Mapping[str, Any]) -> BaseAgentEvent | BaseChatMessage:\n        \"\"\"Create a message from a dictionary of JSON-serializable data.\"\"\"\n        # Get the type of the message from the dictionary.\n        message_type = data.get(\"type\")\n        if message_type is None:\n            raise ValueError(\"Field 'type' is required in the message data to recover the message type.\")\n        if message_type not in self._message_types:\n            raise ValueError(f\"Unknown message type: {message_type}\")\n        if not isinstance(message_type, str):\n            raise ValueError(f\"Message type must be a string, got {type(message_type)}\")\n\n        # Get the class for the message type.\n        message_class = self._message_types[message_type]\n\n        # Create an instance of the message class.\n        assert issubclass(message_class, BaseChatMessage) or issubclass(message_class, BaseAgentEvent)\n        return message_class.load(data)\n\n\nChatMessage = Annotated[\n    TextMessage | MultiModalMessage | StopMessage | ToolCallSummaryMessage | HandoffMessage,\n    Field(discriminator=\"type\"),\n]\n\"\"\"The union type of all built-in concrete subclasses of :class:`BaseChatMessage`.\nIt does not include :class:`StructuredMessage` types.\"\"\"\n","sourceCodeStart":617,"sourceCodeEnd":653,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-agentchat/src/autogen_agentchat/messages.py#L617-L653","documentation":"Thrown by MessageFactory.create() when data['type'] names a message class that was never registered in the factory's registry. The registry only contains built-in types plus anything passed via custom_message_types when the team was constructed, so any other class name is rejected.","triggerScenarios":"Calling create() with {'type': 'MyCustomMessage', ...} when MyCustomMessage was not included in the custom_message_types list of the team (or not registered via MessageFactory.register()). Also happens after renaming a custom message class: old checkpoints refer to the old class name, which is no longer registered.","commonSituations":"Custom message classes used by an agent but forgotten in the team's custom_message_types; loading a checkpoint saved before a class rename; mixing checkpoints between two applications with different registries.","solutions":["Add the missing class to the team constructor: RoundRobinGroupChat(..., custom_message_types=[MyCustomMessage]).","Or register directly on the factory: message_factory.register(MyCustomMessage) before calling create().","If the class was renamed, either re-register under the old name via a subclass (class OldName(NewName): ...) or re-save the state.","Verify the exact string in data['type'] matches the class __name__ used at registration time."],"exampleFix":"# before\nteam = RoundRobinGroupChat([agent1, agent2])  # agent emits MyCustomMessage -> create() fails\n\n# after\nfrom my_messages import MyCustomMessage\nteam = RoundRobinGroupChat([agent1, agent2], custom_message_types=[MyCustomMessage])","handlingStrategy":"validation","validationCode":"def can_create(factory: MessageFactory, data: Mapping[str, Any]) -> bool:\n    return data.get(\"type\") in factory._message_types  # or expose is_registered via a registered probe","typeGuard":"def is_known_type(factory: MessageFactory, data: Mapping[str, Any]) -> bool:\n    t = data.get(\"type\")\n    return isinstance(t, str) and t in factory._message_types","tryCatchPattern":"try:\n    msg = factory.create(data)\nexcept ValueError as e:\n    if str(e).startswith(\"Unknown message type\"):\n        # register and retry\n        factory.register(expected_class)\n        msg = factory.create(data)\n    else:\n        raise","preventionTips":["Centralize all custom message classes in one module and pass the full list to every team's custom_message_types.","After renaming a custom message class, re-save all serialized state.","Log the registered type names alongside deserialization failures."],"tags":["python","autogen","message-factory","custom-message","registry"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}