microsoft/autogen · error · ValueError

Unhandled message in group chat manager: {type(message)}

Error message

Unhandled message in group chat manager: {type(message)}

What it means

Raised by on_unhandled_message on the group chat manager when the runtime delivers a message whose type has no registered handler/subscription match. The manager only handles the internal GroupChat* protocol messages (plus types its subclass registers); anything else arriving on its topic triggers this ValueError. It usually indicates a message-routing or API-usage bug rather than a model problem.

Source

Thrown at python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_base_group_chat_manager.py:326

        This is called when the group chat manager have received all responses from the participants
        for a turn and is ready to select the next speakers for the next turn.

        Args:
            thread: The message thread of the group chat.

        Returns:
            A list of topic types of the selected speakers.
            If only one speaker is selected, a single string is returned instead of a list.
        """
        ...

    @abstractmethod
    async def reset(self) -> None:
        """Reset the group chat manager."""
        ...

    async def on_unhandled_message(self, message: Any, ctx: MessageContext) -> None:
        raise ValueError(f"Unhandled message in group chat manager: {type(message)}")

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Do not publish messages to the team's internal topics; pass tasks via Team.run() / run_stream() so the GroupChatStart protocol is used.
2. If you subclass a group chat manager and introduce new message types, add matching handlers and subscriptions (see SequentialRoutedAgent/routed agent registration).
3. Log type(message) and the topic it arrived on to find which publisher is misaddressing traffic.

Example fix

// before
await runtime.publish_message(UserText(content="hi"), DefaultTopicId(type=team_group_topic))  # wrong topic

// after
await team.run(task="hi")  # task enters via the public API

try:
    await team.run(task="hello")
except ValueError as e:
    if "Unhandled message in group chat manager" in str(e):
        # a publisher sent a non-protocol type to the manager topic; fix routing
        ...

When it happens

Trigger: Publishing a custom or user message type directly to the group topic type instead of running it through team.run_stream()/run(); extending a manager subclass without registering a handler for a new internal message type; sending an agent's raw output event to the manager topic.

Common situations: Custom orchestration code that uses the low-level runtime alongside a team; version upgrades that add new GroupChat* message types while a serialized/handcrafted message is replayed; misconfigured topic subscriptions in a custom manager.

Related errors

• Unhandled message in agent container: {type(message)}
• Message must have a receiver to be sent.
• ToolCallMessage is not supported when message.From is not th
• Speaker {speaker_name} not found in participant names.
• Agent is already bound to a different runtime

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