{"record":{"id":"a37eff1347bb8e81","repo":"microsoft/autogen","slug":"target-node-target-name-must-be-added-before-a","errorCode":null,"errorMessage":"Target node '{target_name}' must be added before adding an edge.","messagePattern":"Target node '(.+?)' must be added before adding an edge\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_graph_builder.py","lineNumber":141,"sourceCode":"            source: Source node (agent name or agent object)\n            target: Target node (agent name or agent object)\n            condition: Optional condition for edge activation.\n                If string, activates when substring is found in message.\n                If callable, activates when function returns True for the message.\n\n        Returns:\n            Self for method chaining\n\n        Raises:\n            ValueError: If source or target node doesn't exist in the builder\n        \"\"\"\n        source_name = self._get_name(source)\n        target_name = self._get_name(target)\n\n        if source_name not in self.nodes:\n            raise ValueError(f\"Source node '{source_name}' must be added before adding an edge.\")\n        if target_name not in self.nodes:\n            raise ValueError(f\"Target node '{target_name}' must be added before adding an edge.\")\n        if activation_group is None:\n            activation_group = target_name\n        if activation_condition is None:\n            activation_condition = \"all\"\n        self.nodes[source_name].edges.append(\n            DiGraphEdge(\n                target=target_name,\n                condition=condition,\n                activation_group=activation_group,\n                activation_condition=activation_condition,\n            )\n        )\n        return self\n\n    def add_conditional_edges(\n        self, source: Union[str, ChatAgent], condition_to_target: Dict[str, Union[str, ChatAgent]]\n    ) -> \"DiGraphBuilder\":\n        \"\"\"Add multiple conditional edges from a source node based on keyword checks.","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_graph_builder.py#L123-L159","documentation":"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.","triggerScenarios":"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.","commonSituations":"Name/object mixups when the same logical agent is instantiated twice; generated graphs with inconsistent identifiers; renaming an agent but not all edge references.","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."],"exampleFix":"// before\nagents = {\"researcher\": AssistantAgent(name=\"researcher\", ...)}\nbuilder.add_edge(agents[\"researcher\"], \"writer\")  # 'writer' node never created anywhere\n\n// after\nwriter = AssistantAgent(name=\"writer\", model_client=client)\nbuilder.add_edge(agents[\"researcher\"], writer)  # target object creates the node","handlingStrategy":"validation","validationCode":"def edge_target_valid(builder: DiGraphBuilder, target) -> bool:\n    # valid if known node OR a new agent object that add_edge can register\n    if isinstance(target, str):\n        return target in builder.nodes\n    return hasattr(target, \"name\")","typeGuard":"def is_known_or_new_agent(builder: DiGraphBuilder, t) -> bool:\n    if isinstance(t, str):\n        return t in builder.nodes\n    return isinstance(t, ChatAgent) or isinstance(t, Team)","tryCatchPattern":"try:\n    builder.add_edge(source, target)\nexcept ValueError as e:\n    if \"Target node\" in str(e) and \"must be added\" in str(e):\n        # fix the target name string or pass the actual agent object\n        ...","preventionTips":["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."],"tags":["graph","builder","edges","configuration"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}