microsoft/autogen · error · ValueError

Message type {message_type} is already registered.

Error message

Message type {message_type} is already registered.

What it means

MessageFactory.register raises ValueError when a message type whose class name is already present in the registry is registered again. Registration is keyed by __name__, so even two different classes sharing a class name collide. Built-in types (TextMessage, ToolCallExecutionEvent, CodeExecutionEvent, ...) are pre-registered.

Source

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

        self._message_types[MemoryQueryEvent.__name__] = MemoryQueryEvent
        self._message_types[UserInputRequestedEvent.__name__] = UserInputRequestedEvent
        self._message_types[ModelClientStreamingChunkEvent.__name__] = ModelClientStreamingChunkEvent
        self._message_types[ThoughtEvent.__name__] = ThoughtEvent
        self._message_types[SelectSpeakerEvent.__name__] = SelectSpeakerEvent
        self._message_types[CodeGenerationEvent.__name__] = CodeGenerationEvent
        self._message_types[CodeExecutionEvent.__name__] = CodeExecutionEvent

    def is_registered(self, message_type: type[BaseAgentEvent | BaseChatMessage]) -> bool:
        """Check if a message type is registered with the factory."""
        # Get the class name of the message type.
        class_name = message_type.__name__
        # Check if the class name is already registered.
        return class_name in self._message_types

    def register(self, message_type: type[BaseAgentEvent | BaseChatMessage]) -> None:
        """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)}")

View on GitHub (pinned to 027ecf0a37)

Solutions

  1. Check factory.is_registered(MyMessageType) before registering
  2. Run registration once at application startup, not per request/cell
  3. Give custom message types unique class names that do not collide with built-ins

Example fix

# before
factory.register(MyEvent)  # raises if run twice (notebook re-run)

# after
if not factory.is_registered(MyEvent):
    factory.register(MyEvent)
Defensive patterns

Strategy: validation

Validate before calling

if not factory.is_registered(MyMessageType):
    factory.register(MyMessageType)

Try / catch

try:
    factory.register(MyMessageType)
except ValueError as e:
    if "already registered" not in str(e):
        raise  # different registration error (e.g. wrong base class)

Prevention

When it happens

Trigger: Re-registering a built-in type (e.g. factory.register(TextMessage)); registering a custom class whose name shadows a built-in or a previously registered custom type; running registration code repeatedly (e.g. module re-import or per-request init).

Common situations: App startup code that registers custom message types being executed twice (hot reload, notebooks re-running cells); subclassing a built-in message but keeping the same class name via type() factories.

Related errors

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