microsoft/autogen · error · ValueError

The target {message.target} is not one of the participants {

Error message

The target {message.target} is not one of the participants {self._participant_names}. If you are resuming Swarm with a new HandoffMessage make sure to set the target to a valid participant as the target.

What it means

SwarmGroupChatManager.validate_group_state raises ValueError when a HandoffMessage in the task's start messages targets a name that is not among the team's participants. The swarm routes control to the handoff target, so an invalid target has nowhere to go.

Source

Thrown at python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_swarm_group_chat.py:54

            participant_topic_types,
            participant_names,
            participant_descriptions,
            output_message_queue,
            termination_condition,
            max_turns,
            message_factory,
            emit_team_events,
        )
        self._current_speaker = self._participant_names[0]

    async def validate_group_state(self, messages: List[BaseChatMessage] | None) -> None:
        """Validate the start messages for the group chat."""
        # Check if any of the start messages is a handoff message.
        if messages:
            for message in messages:
                if isinstance(message, HandoffMessage):
                    if message.target not in self._participant_names:
                        raise ValueError(
                            f"The target {message.target} is not one of the participants {self._participant_names}. "
                            "If you are resuming Swarm with a new HandoffMessage make sure to set the target to a valid participant as the target."
                        )
                    return

        # Check if there is a handoff message in the thread that is not targeting a valid participant.
        for existing_message in reversed(self._message_thread):
            if isinstance(existing_message, HandoffMessage):
                if existing_message.target not in self._participant_names:
                    raise ValueError(
                        f"The existing handoff target {existing_message.target} is not one of the participants {self._participant_names}. "
                        "If you are resuming Swarm with a new task make sure to include in your task "
                        "a HandoffMessage with a valid participant as the target. For example, if you are "
                        "resuming from a HandoffTermination, make sure the new task is a HandoffMessage "
                        "with a valid participant as the target."
                    )
                # The latest handoff message should always target a valid participant.
                # Do not look past the latest handoff message.

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Set the HandoffMessage target to a name present in this Swarm's participants (match agent.name exactly).
2. When resuming from HandoffTermination, take the target from your new task design and verify against [p.name for p in participants].
3. Rebuild the swarm with the intended target participant if it was removed.

Example fix

# before
await swarm.run(task=HandoffMessage(content="next", target="helper", source="researcher"))  # no 'helper'

# after
await swarm.run(task=HandoffMessage(content="next", target="coder", source="researcher"))  # exact participant name

participant_names = [a.name for a in agents]
if isinstance(task_message, HandoffMessage):
    assert task_message.target in participant_names, f"target must be one of {participant_names}"

def is_valid_handoff_target(msg: HandoffMessage, participant_names: Sequence[str]) -> bool:
    return msg.target in participant_names

When it happens

Trigger: Calling team.run(task=HandoffMessage(target="agent_x", ...)) where agent_x is not in this Swarm's participants; resuming a swarm run with a handoff message copied from a differently-composed team.

Common situations: Resuming after HandoffTermination and constructing the new task HandoffMessage with a stale or misspelled target; changing the participant roster between runs while reusing saved handoff messages.

Related errors

• The existing handoff target {existing_message.target} is not
• Handoff name '{name}' is not a valid identifier.
• The first participant must be able to produce a handoff mess
• All agents must have a name.
• All agents must have a unique name.

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