microsoft/autogen · error · ValueError

Source node '{source_name}' must be added before adding an e

Error message

Source node '{source_name}' must be added before adding an edge.

What it means

Raised by DiGraphBuilder.add_edge when the source endpoint of the edge is not a node already known to the builder. Nodes come into existence only through add_edge (both endpoints), so referencing a source agent/object that was never used in a previous add_edge — or a name string that does not match any existing node — is rejected.

Source

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

        Args:
            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]]

View on GitHub (pinned to 027ecf0a37)

Solutions

Ensure the source node exists: it must have appeared as an endpoint of a prior add_edge, or be the same object/name you are passing now.
When passing names as strings, verify they exactly match the names of agents used elsewhere in the builder.
Construct edges in a deterministic order (entry -> ... -> exit) so sources are always established first.

Example fix

// before
builder.add_edge("reviwer", drafter)  # typo: node 'reviwer' never created correctly downstream

// after
builder.add_edge(reviewer_agent, drafter)  # use the agent objects; both endpoints get created

Defensive patterns

Strategy: validation

Validate before calling

def edge_source_exists(builder: DiGraphBuilder, source) -> bool:
    name = source if isinstance(source, str) else source.name
    return name in builder.nodes
# assert before add_edge when passing name strings

Type guard

def is_known_node(builder: DiGraphBuilder, agent_or_name: ChatAgent | Team | str) -> bool:
    name = agent_or_name if isinstance(agent_or_name, str) else agent_or_name.name
    return name in builder.nodes

Try / catch

try:
    builder.add_edge(source, target)
except ValueError as e:
    if "Source node" in str(e) and "must be added" in str(e):
        # create the source node first (prior add_edge) or fix the name/object
        ...

Prevention

Pass agent objects rather than name strings to add_edge to avoid name mismatches.
Build edges in workflow order so sources are established before being referenced.
Keep a single {name: agent} registry and reference agents through it.

When it happens

Trigger: Calling add_edge(new_agent, other) where new_agent was never an endpoint before but the roles are swapped in your head; passing source as a name string that is misspelled or refers to an agent added under a different name; building edges before wiring participants (e.g. empty participants list while using names).

Common situations: Confusion about which endpoint creates the node when both are new; name/object mismatches when the same agent is passed under aliases; refactoring edge order in generated graphs.

Related errors

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