microsoft/autogen · error · ValueError

Unknown message type: {message_type}

Error message

Unknown message type: {message_type}

What it means

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.

Source

Thrown at python/packages/autogen-agentchat/src/autogen_agentchat/messages.py:635

        """Register a new message type with the factory."""
        if self.is_registered(message_type):
            raise ValueError(f"Message type {message_type} is already registered.")
        if not issubclass(message_type, BaseChatMessage) and not issubclass(message_type, BaseAgentEvent):
            raise ValueError(f"Message type {message_type} must be a subclass of BaseChatMessage or BaseAgentEvent.")
        # Get the class name of the
        class_name = message_type.__name__
        # Check if the class name is already registered.
        # Register the message type.
        self._message_types[class_name] = message_type

    def create(self, data: Mapping[str, Any]) -> BaseAgentEvent | BaseChatMessage:
        """Create a message from a dictionary of JSON-serializable data."""
        # Get the type of the message from the dictionary.
        message_type = data.get("type")
        if message_type is None:
            raise ValueError("Field 'type' is required in the message data to recover the message type.")
        if message_type not in self._message_types:
            raise ValueError(f"Unknown message type: {message_type}")
        if not isinstance(message_type, str):
            raise ValueError(f"Message type must be a string, got {type(message_type)}")

        # Get the class for the message type.
        message_class = self._message_types[message_type]

        # Create an instance of the message class.
        assert issubclass(message_class, BaseChatMessage) or issubclass(message_class, BaseAgentEvent)
        return message_class.load(data)


ChatMessage = Annotated[
    TextMessage | MultiModalMessage | StopMessage | ToolCallSummaryMessage | HandoffMessage,
    Field(discriminator="type"),
]
"""The union type of all built-in concrete subclasses of :class:`BaseChatMessage`.
It does not include :class:`StructuredMessage` types."""

View on GitHub (pinned to 027ecf0a37)

Solutions

  1. Add the missing class to the team constructor: RoundRobinGroupChat(..., custom_message_types=[MyCustomMessage]).
  2. Or register directly on the factory: message_factory.register(MyCustomMessage) before calling create().
  3. If the class was renamed, either re-register under the old name via a subclass (class OldName(NewName): ...) or re-save the state.
  4. Verify the exact string in data['type'] matches the class __name__ used at registration time.

Example fix

# before
team = RoundRobinGroupChat([agent1, agent2])  # agent emits MyCustomMessage -> create() fails

# after
from my_messages import MyCustomMessage
team = RoundRobinGroupChat([agent1, agent2], custom_message_types=[MyCustomMessage])
Defensive patterns

Strategy: validation

Validate before calling

def can_create(factory: MessageFactory, data: Mapping[str, Any]) -> bool:
    return data.get("type") in factory._message_types  # or expose is_registered via a registered probe

Type guard

def is_known_type(factory: MessageFactory, data: Mapping[str, Any]) -> bool:
    t = data.get("type")
    return isinstance(t, str) and t in factory._message_types

Try / catch

try:
    msg = factory.create(data)
except ValueError as e:
    if str(e).startswith("Unknown message type"):
        # register and retry
        factory.register(expected_class)
        msg = factory.create(data)
    else:
        raise

Prevention

When it happens

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

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

Related errors

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/4edbab810dae801d. Report an issue: GitHub.