microsoft/autogen · error · ValueError

Invalid message type in message buffer: {type(message)}

Error message

Invalid message type in message buffer: {type(message)}

What it means

Raised by ChatAgentContainer.load_state when deserializing a saved container state whose message buffer contains an entry that the MessageFactory resolves to something that is not a BaseChatMessage (e.g. an event type, or a payload whose 'type' field maps to the wrong class). The buffer must hold chat messages only; anything else corrupts the agent's input history, so loading is aborted.

Source

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

    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. Load state only into a team constructed with the same participants and custom_message_types as when it was saved.
2. Validate checkpoint JSON before loading: every message_buffer entry must deserialize to a chat message type.
3. Regenerate checkpoints after upgrading autogen versions or changing custom message type registrations.

Example fix

// before
team2 = RoundRobinGroupChat([agent_b])  # different config
await team2.load_state(saved_state)  # buffer types mismatch

// after
team2 = RoundRobinGroupChat([agent_a], custom_message_types=[MyMsg])  # same as save-time config
await team2.load_state(saved_state)

from autogen_agentchat.messages import MessageFactory
factory = MessageFactory()
for custom in CUSTOM_TYPES:
    factory.register_message_type(custom)
state = json.load(open("checkpoint.json"))
for node_state in _iter_agent_states(state):
    for entry in node_state.get("message_buffer", []):
        obj = factory.create(entry)
        if not isinstance(obj, BaseChatMessage):
            raise ValueError(f"Checkpoint contains non-message entry of type {type(obj)}")

def is_chat_message_payload(factory: MessageFactory, data: dict) -> bool:
    return isinstance(factory.create(data), BaseChatMessage)

try:
    await team.load_state(saved)
except ValueError as e:
    if "Invalid message type in message buffer" in str(e):
        # checkpoint incompatible with current team config; rebuild config or regenerate checkpoint
        ...

When it happens

Trigger: Calling team.load_state(saved_state) where the checkpoint was produced by a different team configuration whose message factory maps the same type string to a non-message class; hand-editing checkpoint JSON and putting an event type in message_buffer; version upgrade changing factory type mappings.

Common situations: Persisting team state across service restarts; sharing checkpoints between environments with different custom_message_types declarations; schema drift after a library upgrade.

Related errors

• State is not initialized.
• Cannot convert state of type {this.deserializedValue.GetType
• Cannot deserialize state to {typeof(T)}.
• Message type {message.__class__} is not registered.
• Failed to fetch messages

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