microsoft/semantic-kernel · error · InvalidOperationException

Proxy step does not have linked steps to it, link step edges

Error message

Proxy step does not have linked steps to it, link step edges to proxy or remove proxy step

What it means

Thrown by ProcessProxyBuilder.BuildStep when none of the registered external topics have been linked to a step edge (all entries in _externalTopicUsage are false). A proxy step with no linked edges serves no purpose and indicates a configuration error — the proxy was added but never wired to any publishing step.

Source

Thrown at dotnet/src/Experimental/Process.Core/ProcessProxyBuilder.cs:72

        {
            throw new InvalidOperationException($"Topic name {topicName} is not registered as proxy publish event, register first before using");
        }

        if (usedTopic)
        {
            throw new InvalidOperationException($"Topic name {topicName} is is already linked to another step edge");
        }

        this._eventMetadata[eventData.EventName] = new() { EventId = eventData.EventId, TopicName = topicName };
        this._externalTopicUsage[topicName] = true;
    }

    /// <inheritdoc/>
    internal override KernelProcessStepInfo BuildStep(ProcessBuilder processBuilder, KernelProcessStepStateMetadata? stateMetadata = null)
    {
        if (this._externalTopicUsage.All(topic => !topic.Value))
        {
            throw new InvalidOperationException("Proxy step does not have linked steps to it, link step edges to proxy or remove proxy step");
        }

        KernelProcessProxyStateMetadata proxyMetadata = new()
        {
            Name = this.Name,
            Id = this.Id,
            EventMetadata = this._eventMetadata,
            PublishTopics = this._externalTopicUsage.ToList().Select(topic => topic.Key).ToList(),
        };

        // Build the edges first
        var builtEdges = this.Edges.ToDictionary(kvp => kvp.Key, kvp => kvp.Value.Select(e => e.Build()).ToList());

        KernelProcessStepState state = new(this.Name, this.Version, this.Id);

        return new KernelProcessProxy(state, builtEdges)
        {
            ProxyMetadata = proxyMetadata

View on GitHub (pinned to c028a0c7dc)

Solutions

Call LinkTopicToStepEdgeInfo for at least one topic before building the process.
If the proxy is not needed, remove the AddProxyStep call instead of leaving an unlinked proxy.
Review the process construction logic to ensure all proxy steps are fully wired before Build.

Example fix

// before
var proxy = process.AddProxyStep("myProxy", externalTopics: new[] { "topicA" });
// forgot to link any step edge to topicA
var kernelProcess = process.Build(); // throws in BuildStep

// after — link a step edge before building
proxy.LinkTopicToStepEdgeInfo("topicA", sourceStep, eventData);
var kernelProcess = process.Build();

Defensive patterns

Strategy: validation

Validate before calling

// Before building, verify each proxy has at least one linked edge
// (requires tracking link calls; if not possible, catch at Build time)
if (!hasLinkedAnyEdge)
    throw new InvalidOperationException("Proxy step has no linked edges. Link a step edge or remove the proxy.");

var kernelProcess = process.Build();

Try / catch

try
{
    var kernelProcess = process.Build();
}
catch (InvalidOperationException ex) when (ex.Message.Contains("does not have linked steps"))
{
    logger.LogError("Proxy step not wired: {Message}", ex.Message);
    // Remove the proxy or add the missing edge links, then rebuild
}

Prevention

Always call LinkTopicToStepEdgeInfo for at least one topic before Build.
If a proxy is not needed, remove it rather than leaving it unlinked.
Add a pre-build validation pass that checks all proxy steps have at least one linked edge.

When it happens

Trigger: Calling BuildStep (directly or via ProcessBuilder.Build) on a proxy step where LinkTopicToStepEdgeInfo was never called for any topic, or where all link calls were skipped.

Common situations: Adding a proxy step but forgetting to wire step edges to it; building the process before completing the edge graph; conditional code that skips edge linking under certain configurations; early prototype code with a placeholder proxy.

Related errors

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