microsoft/semantic-kernel · error · ArgumentException

An orchestration is referencing a node with Id `{action.Node

Error message

An orchestration is referencing a node with Id `{action.Node}` that does not exist.

What it means

Thrown by WorkflowBuilder when a `then` action's destination `Node` does not resolve to a registered step and is not the `"End"` terminal sentinel. The builder looks up the destination in `_stepBuilders`; an unresolved id means the orchestration points at a node that was never declared. It is an ArgumentException raised inside the `thenActions` loop in `AddOrchestrationStepAsync`.

Source

Thrown at dotnet/src/Experimental/Process.Core/Workflow/WorkflowBuilder.cs:302

            }

            // Now that we have a validated edge source, we can add the then actions
            foreach (var action in thenActions)
            {
                if (action is null || string.IsNullOrWhiteSpace(action.Node))
                {
                    throw new ArgumentException("A complete then action is required for orchestration steps.");
                }

                if (!this._stepBuilders.TryGetValue(action.Node, out ProcessStepBuilder? destinationStepBuilder))
                {
                    if (action.Node.Equals("End", StringComparison.OrdinalIgnoreCase))
                    {
                        edgeBuilder.StopProcess();
                        continue;
                    }

                    throw new ArgumentException($"An orchestration is referencing a node with Id `{action.Node}` that does not exist.");
                }

                // Add the edge to the node
                edgeBuilder = edgeBuilder.SendEventTo(new ProcessFunctionTargetBuilder(destinationStepBuilder));
            }
        }

        return Task.CompletedTask;
    }

    #endregion

    #region FromProcess

    /// <summary>
    /// Builds a workflow from a kernel process.
    /// </summary>
    /// <param name="process"></param>

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Verify every `then.node` value matches a declared step Id exactly, or is the literal `"End"`.
2. After deleting or renaming a step, grep the workflow for stale `then.node` references and update them.
3. Run a pre-build integrity check mapping all `then.node` values against the registered step set.

Example fix

// before
then:
  - node: OldStepName
// after
then:
  - node: RenamedStep

var stepIds = new HashSet<string>(workflow.Nodes.Select(n => n.Id), StringComparer.Ordinal);
stepIds.Add("End");
foreach (var step in workflow.Orchestration)
{
    if (step.Then is null) continue;
    foreach (var action in step.Then)
    {
        if (action is null) continue;
        if (!stepIds.Contains(action.Node))
            throw new InvalidOperationException($"then.node '{action.Node}' is not a declared step and not 'End'.");
    }
}

bool IsValidThenNode(Workflow wf, string node) =>
    node.Equals("End", StringComparison.OrdinalIgnoreCase)
    || wf.Nodes.Any(n => string.Equals(n.Id, node, StringComparison.Ordinal));

try { await builder.BuildAsync(); }
catch (ArgumentException ex) when (ex.Message.Contains("does not exist"))
{ _logger.LogError(ex, "Then action references unknown node."); throw; }

When it happens

Trigger: Reference a `then.node` value that is not in the `steps` collection and is not `"End"`; rename a destination step without updating incoming `then` references; use a node id with mismatched casing/whitespace.

Common situations: Refactoring a graph and deleting a step that other steps still route to; typos in hand-authored YAML; version upgrades that changed step id conventions.

Related errors

• An orchestration is referencing a node with Id `{listenCondi
• A complete then action is required for orchestration steps.
• Only one `Default` handler is allowed in a group of event ha
• `Default` handlers must not have an eval expression.
• Only one `Always` handler is allowed in a group of event han

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/499cf7078fa01e1a. Report an issue: GitHub.