microsoft/autogen · error · ValueError

Unhandled message in agent container: {type(message)}

Error message

Unhandled message in agent container: {type(message)}

What it means

Raised by ChatAgentContainer.on_unhandled_message when the runtime delivers a message type the container has no handler for. The container only handles the internal GroupChat* protocol messages; publishing any other type directly to a participant's topic (instead of going through the team's public API) or misconfigured subscriptions trigger this ValueError.

Source

Thrown at python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_chat_agent_container.py:195

    async def handle_pause(self, message: GroupChatPause, ctx: MessageContext) -> None:
        """Handle a pause event by pausing the agent."""
        if isinstance(self._agent, Team):
            # If the agent is a team, pause the team.
            await self._agent.pause()
        else:
            await self._agent.on_pause(ctx.cancellation_token)

    @rpc
    async def handle_resume(self, message: GroupChatResume, ctx: MessageContext) -> None:
        """Handle a resume event by resuming the agent."""
        if isinstance(self._agent, Team):
            # If the agent is a team, resume the team.
            await self._agent.resume()
        else:
            await self._agent.on_resume(ctx.cancellation_token)

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

    async def save_state(self) -> Mapping[str, Any]:
        agent_state = await self._agent.save_state()
        state = ChatAgentContainerState(
            agent_state=agent_state, message_buffer=[message.dump() for message in self._message_buffer]
        )
        return state.model_dump()

    async def load_state(self, state: Mapping[str, Any]) -> None:
        container_state = ChatAgentContainerState.model_validate(state)
        self._message_buffer = []
        for message_data in container_state.message_buffer:
            message = self._message_factory.create(message_data)
            if isinstance(message, BaseChatMessage):
                self._message_buffer.append(message)
            else:
                raise ValueError(f"Invalid message type in message buffer: {type(message)}")
        await self._agent.load_state(container_state.agent_state)

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Route all tasks through Team.run()/run_stream(); never publish directly to participant topics.
2. If extending the protocol in a custom manager/container pair, register handlers for every new message type in the container.
3. Align autogen-core and autogen-agentchat versions so internal GroupChat* message types match.

Example fix

// before
await runtime.publish_message(MyTaskMessage(...), DefaultTopicId(type="agent1"))  # unhandled

// after
await team.run(task=TextMessage(content="do it", source="user"))

try:
    await team.run(task=text)
except ValueError as e:
    if "Unhandled message in agent container" in str(e):
        # something published a non-protocol type to a participant topic; audit publishers
        ...

When it happens

Trigger: Publishing application messages straight to an agent's topic via the runtime; custom orchestration code bypassing team.run(); replaying messages of internal types from a different autogen version against a current container.

Common situations: Mixing low-level autogen_core runtime publishing with high-level agentchat teams; custom group chat managers that introduce new protocol message types without updating container handlers; version skew between serialized messages and installed library.

Related errors

• Unhandled message in group chat manager: {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/cbb909a71abd1502. Report an issue: GitHub.