microsoft/autogen · error · ValueError

Target node '{target_name}' must be added before adding an e

Error message

Target node '{target_name}' must be added before adding an edge.

What it means

Raised by DiGraphBuilder.add_edge when the target endpoint of the edge is not a node known to the builder. The target must either be a brand-new agent (which add_edge would register as a node) or an already-known node; the failure typically means a name string was passed that matches no existing node while the builder also cannot create it from context, or the participants list passed to GraphFlow does not contain that agent.

Source

Thrown at python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_graph_builder.py:141

            source: Source node (agent name or agent object)
            target: Target node (agent name or agent object)
            condition: Optional condition for edge activation.
                If string, activates when substring is found in message.
                If callable, activates when function returns True for the message.

        Returns:
            Self for method chaining

        Raises:
            ValueError: If source or target node doesn't exist in the builder
        """
        source_name = self._get_name(source)
        target_name = self._get_name(target)

        if source_name not in self.nodes:
            raise ValueError(f"Source node '{source_name}' must be added before adding an edge.")
        if target_name not in self.nodes:
            raise ValueError(f"Target node '{target_name}' must be added before adding an edge.")
        if activation_group is None:
            activation_group = target_name
        if activation_condition is None:
            activation_condition = "all"
        self.nodes[source_name].edges.append(
            DiGraphEdge(
                target=target_name,
                condition=condition,
                activation_group=activation_group,
                activation_condition=activation_condition,
            )
        )
        return self

    def add_conditional_edges(
        self, source: Union[str, ChatAgent], condition_to_target: Dict[str, Union[str, ChatAgent]]
    ) -> "DiGraphBuilder":
        """Add multiple conditional edges from a source node based on keyword checks.

View on GitHub (pinned to 027ecf0a37)

Solutions

Pass the actual agent objects to add_edge instead of name strings, guaranteeing identity.
If using names, ensure they exactly match existing node names (case-sensitive) created by prior add_edge calls.
Keep a single source-of-truth dict {name: agent} and reference agents through it everywhere.

Example fix

// before
agents = {"researcher": AssistantAgent(name="researcher", ...)}
builder.add_edge(agents["researcher"], "writer")  # 'writer' node never created anywhere

// after
writer = AssistantAgent(name="writer", model_client=client)
builder.add_edge(agents["researcher"], writer)  # target object creates the node

Defensive patterns

Strategy: validation

Validate before calling

def edge_target_valid(builder: DiGraphBuilder, target) -> bool:
    # valid if known node OR a new agent object that add_edge can register
    if isinstance(target, str):
        return target in builder.nodes
    return hasattr(target, "name")

Type guard

def is_known_or_new_agent(builder: DiGraphBuilder, t) -> bool:
    if isinstance(t, str):
        return t in builder.nodes
    return isinstance(t, ChatAgent) or isinstance(t, Team)

Try / catch

try:
    builder.add_edge(source, target)
except ValueError as e:
    if "Target node" in str(e) and "must be added" in str(e):
        # fix the target name string or pass the actual agent object
        ...

Prevention

Avoid duplicate instances: reuse the same agent object referenced by earlier add_edge calls.
Validate name strings against builder.nodes before use (case-sensitive).
Construct graphs from a single agent registry to keep identifiers consistent.

When it happens

Trigger: Passing target as a misspelled or differently-cased name string; referencing an agent object that differs from the one used in earlier add_edge calls (duplicate instances of 'same-named' agents); building the graph with names while GraphFlow receives a participants list missing that agent.

Common situations: Name/object mixups when the same logical agent is instantiated twice; generated graphs with inconsistent identifiers; renaming an agent but not all edge references.

Related errors

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