microsoft/autogen · error · ValueError

Invalid state format. The expected state format has changed

Error message

Invalid state format. The expected state format has changed since v0.4.9. Please read the release note on GitHub.

What it means

A pydantic ValidationError while TeamState.model_validate(state) runs is caught and re-raised as this friendlier ValueError: the dict passed to load_state() does not match the current TeamState schema, which changed in v0.4.9. The original validation error is chained as __cause__ for details.

Source

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

            raise RuntimeError("The team cannot be loaded while it is running.")
        self._is_running = True

        try:
            team_state = TeamState.model_validate(state)
            # Load the state of all participants.
            for name, agent_type in zip(self._participant_names, self._participant_topic_types, strict=True):
                agent_id = AgentId(type=agent_type, key=self._team_id)
                if name not in team_state.agent_states:
                    raise ValueError(f"Agent state for {name} not found in the saved state.")
                await self._runtime.agent_load_state(agent_id, team_state.agent_states[name])
            # Load the state of the group chat manager.
            agent_id = AgentId(type=self._group_chat_manager_topic_type, key=self._team_id)
            if self._group_chat_manager_name not in team_state.agent_states:
                raise ValueError(f"Agent state for {self._group_chat_manager_name} not found in the saved state.")
            await self._runtime.agent_load_state(agent_id, team_state.agent_states[self._group_chat_manager_name])

        except ValidationError as e:
            raise ValueError(
                "Invalid state format. The expected state format has changed since v0.4.9. "
                "Please read the release note on GitHub."
            ) from e

        finally:
            # Indicate that the team is no longer running.
            self._is_running = False

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Read the chained error for the exact field mismatch: except ValueError as e: print(e.__cause__).
2. Discard or regenerate old checkpoints — the pre-0.4.9 format is not loadable; start a fresh conversation and re-save.
3. If migrating programmatically, transform the old dict into the current TeamState schema (see the v0.4.9 release notes) before calling load_state().

Example fix

# before
await team.load_state(old_checkpoint)  # ValueError: invalid state format

# after
try:
    await team.load_state(old_checkpoint)
except ValueError as e:
    print("schema errors:", e.__cause__)  # decide: migrate or start fresh
    raise

from autogen_agentchat.teams._group_chat._base_group_chat import TeamState
try:
    TeamState.model_validate(state)  # schema pre-check
except Exception:
    raise ValueError("state file is not in the current TeamState format; regenerate it")

try:
    await team.load_state(state)
except ValueError as e:
    if "state format has changed" in str(e):
        logger.error("stale checkpoint (pre-0.4.9): %s", e.__cause__)
        state = None  # start a fresh session
    else:
        raise

When it happens

Trigger: Passing a pre-0.4.9 state dict (different field names/structure) to load_state(); passing arbitrary JSON that is not a TeamState at all; truncated or re-serialized state files that lost nested types.

Common situations: Upgrading autogen-agentchat past 0.4.9 and loading old checkpoints; persisting state through a layer that mangles nested structures; loading a state file from a different library version.

Related errors

• The team cannot be loaded while it is running.
• Agent state for {name} not found in the saved state.
• Agent state for {self._group_chat_manager_name} not found in
• Expected Memory, List[Memory], or None, got {type(memory)}
• The model does not support function calling.

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