microsoft/semantic-kernel · error · InvalidOperationException

Step name {builder.Name} is already used, assign a different

Error message

Step name {builder.Name} is already used, assign a different name for step

What it means

Thrown by ProcessBuilder.AddStep when a step with the same Name has already been added to the process's _steps list. Step names must be unique within a process because they serve as identifiers for edge routing and state persistence.

Source

Thrown at dotnet/src/Experimental/Process.Core/ProcessBuilder.cs:167

        this._steps.Add(stepBuilder);
    }

    /// <summary>
    /// Check to ensure stepName is not used yet in another step
    /// </summary>
    private bool StepNameAlreadyExists(string stepName)
    {
        return this._steps.Select(step => step.Name).Contains(stepName);
    }

    /// <summary>
    /// Verify step is unique and add to the process.
    /// </summary>
    private TBuilder AddStep<TBuilder>(TBuilder builder, IReadOnlyList<string>? aliases) where TBuilder : ProcessStepBuilder
    {
        if (this.StepNameAlreadyExists(builder.Name))
        {
            throw new InvalidOperationException($"Step name {builder.Name} is already used, assign a different name for step");
        }

        if (aliases != null && aliases.Count > 0)
        {
            builder.Aliases = aliases;
        }

        this._steps.Add(builder);

        return builder;
    }

    #region Public Interface

    /// <summary>
    /// A read-only collection of steps in the process.
    /// </summary>
    public IReadOnlyList<ProcessStepBuilder> Steps => this._steps.AsReadOnly();

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Provide a unique 'id' parameter when adding multiple steps of the same type: AddStepFromType<MyStep>(id: "step1") and AddStepFromType<MyStep>(id: "step2").
2. Rename steps or use different step types if uniqueness cannot be achieved via id.
3. Audit existing step names in the process before adding a new one.

Example fix

// before — two steps of the same type, default name collides
process.AddStepFromType<MyStep>();
process.AddStepFromType<MyStep>(); // throws — both named 'MyStep'

// after
process.AddStepFromType<MyStep>(id: "step1");
process.AddStepFromType<MyStep>(id: "step2");

public static void EnsureUniqueStepName(ProcessBuilder process, string stepName)
{
    if (process.Steps.Any(s => s.Name == stepName))
    {
        throw new InvalidOperationException($"Step name '{stepName}' already exists in process '{process.Name}'.");
    }
}

When it happens

Trigger: Calling AddStepFromType, AddStepFromAgent, or AddStepFromProcess twice with steps that resolve to the same name. The default name for AddStepFromType is typeof(TStep).Name, so adding two instances of the same step type without an explicit id triggers this.

Common situations: Adding two steps of the same type (e.g., two ProcessStepBuilder<MyStep>) without providing unique id parameters. Adding a step whose name collides with a previously added sub-process or map step. Reusing the same builder instance or name across different parts of the process.

Related errors

• At least one action must be provided.
• All declarative agents must have an Id or a Name assigned.
• AgentDefinition Id must be set
• Expression must be a property access expression
• Only one `Default` handler is allowed in a group of event ha

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