microsoft/autogen · error · ValueError

Message type {msg.class} is not registered with the mess

Error message

Message type {msg.__class__} is not registered with the message factory. Please register it with the message factory by adding it to the custom_message_types list when creating the team.

What it means

Before a run starts, the team verifies every message in the task is a class known to its MessageFactory so that serialization/round-trip of the session will work. Custom message types must be declared via custom_message_types at team construction; built-ins are registered automatically.

Source

Thrown at python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_base_group_chat.py:477

        elif isinstance(task, str):
            messages = [TextMessage(content=task, source="user")]
        elif isinstance(task, BaseChatMessage):
            messages = [task]
        elif isinstance(task, list):
            if not task:
                raise ValueError("Task list cannot be empty.")
            messages = []
            for msg in task:
                if not isinstance(msg, BaseChatMessage):
                    raise ValueError("All messages in task list must be valid BaseChatMessage types")
                messages.append(msg)
        else:
            raise ValueError("Task must be a string, a BaseChatMessage, or a list of BaseChatMessage.")
        # Check if the messages types are registered with the message factory.
        if messages is not None:
            for msg in messages:
                if not self._message_factory.is_registered(msg.__class__):
                    raise ValueError(
                        f"Message type {msg.__class__} is not registered with the message factory. "
                        "Please register it with the message factory by adding it to the "
                        "custom_message_types list when creating the team."
                    )

        if self._is_running:
            raise ValueError("The team is already running, it cannot run again until it is stopped.")
        self._is_running = True

        if self._embedded_runtime:
            # Start the embedded runtime.
            assert isinstance(self._runtime, SingleThreadedAgentRuntime)
            self._runtime.start()

        if not self._initialized:
            await self._init(self._runtime)

        shutdown_task: asyncio.Task[None] | None = None

View on GitHub (pinned to 027ecf0a37)

Solutions

Recreate the team with custom_message_types=[MyCustomMessage, ...] included.
Keep a single module-level list of all custom message classes and pass it to every team constructor.
As a stopgap, convert the custom message to a TextMessage before passing it as a task.

Example fix

# before
team = RoundRobinGroupChat([agent])  # agent produces MyCustomMessage
await team.run(task=[MyCustomMessage(content="x")])  # ValueError

# after
team = RoundRobinGroupChat([agent], custom_message_types=[MyCustomMessage])
await team.run(task=[MyCustomMessage(content="x")])

Defensive patterns

Strategy: validation

Validate before calling

CUSTOM_MESSAGES = [MyCustomMessage, OtherCustomMessage]  # single source of truth
team = RoundRobinGroupChat(agents, custom_message_types=CUSTOM_MESSAGES)

Prevention

Maintain one module-level list of custom message types and pass it to every team constructor.
When an agent's produced_message_types includes a custom class, mirror it in the team config.
Add a startup check comparing agent.produced_message_types against the team's registered types.

When it happens

Trigger: team.run_stream(task=[MyCustomMessage(...)]) when MyCustomMessage was not listed in custom_message_types when the team was created. Registration cannot be done after construction, so this check fails the run before any agent executes.

Common situations: An agent returns a custom message type that was registered for the agent but the user forgot the matching custom_message_types entry on the team; adding a new custom message class to an agent without updating the team constructor.

Related errors

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