{"record":{"id":"cbb909a71abd1502","repo":"microsoft/autogen","slug":"unhandled-message-in-agent-container-type-messag","errorCode":null,"errorMessage":"Unhandled message in agent container: {type(message)}","messagePattern":"Unhandled message in agent container: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_chat_agent_container.py","lineNumber":195,"sourceCode":"    async def handle_pause(self, message: GroupChatPause, ctx: MessageContext) -> None:\n        \"\"\"Handle a pause event by pausing the agent.\"\"\"\n        if isinstance(self._agent, Team):\n            # If the agent is a team, pause the team.\n            await self._agent.pause()\n        else:\n            await self._agent.on_pause(ctx.cancellation_token)\n\n    @rpc\n    async def handle_resume(self, message: GroupChatResume, ctx: MessageContext) -> None:\n        \"\"\"Handle a resume event by resuming the agent.\"\"\"\n        if isinstance(self._agent, Team):\n            # If the agent is a team, resume the team.\n            await self._agent.resume()\n        else:\n            await self._agent.on_resume(ctx.cancellation_token)\n\n    async def on_unhandled_message(self, message: Any, ctx: MessageContext) -> None:\n        raise ValueError(f\"Unhandled message in agent container: {type(message)}\")\n\n    async def save_state(self) -> Mapping[str, Any]:\n        agent_state = await self._agent.save_state()\n        state = ChatAgentContainerState(\n            agent_state=agent_state, message_buffer=[message.dump() for message in self._message_buffer]\n        )\n        return state.model_dump()\n\n    async def load_state(self, state: Mapping[str, Any]) -> None:\n        container_state = ChatAgentContainerState.model_validate(state)\n        self._message_buffer = []\n        for message_data in container_state.message_buffer:\n            message = self._message_factory.create(message_data)\n            if isinstance(message, BaseChatMessage):\n                self._message_buffer.append(message)\n            else:\n                raise ValueError(f\"Invalid message type in message buffer: {type(message)}\")\n        await self._agent.load_state(container_state.agent_state)","sourceCodeStart":177,"sourceCodeEnd":213,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_chat_agent_container.py#L177-L213","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Route all tasks through Team.run()/run_stream(); never publish directly to participant topics.","If extending the protocol in a custom manager/container pair, register handlers for every new message type in the container.","Align autogen-core and autogen-agentchat versions so internal GroupChat* message types match."],"exampleFix":"// before\nawait runtime.publish_message(MyTaskMessage(...), DefaultTopicId(type=\"agent1\"))  # unhandled\n\n// after\nawait team.run(task=TextMessage(content=\"do it\", source=\"user\"))","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    await team.run(task=text)\nexcept ValueError as e:\n    if \"Unhandled message in agent container\" in str(e):\n        # something published a non-protocol type to a participant topic; audit publishers\n        ...","preventionTips":["Send tasks only through Team.run/run_stream, never runtime.publish_message to agent topics.","When extending the protocol, update container handlers alongside manager handlers.","Pin compatible autogen-core/agentchat versions in requirements."],"tags":["group-chat","message-routing","runtime","api-misuse"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}