What causes "The proxy step can only handle 1 parameter object" in microsoft/semantic-kernel?

Ensure edges targeting a KernelProcessProxy step deliver exactly one value in the message.

microsoft/semantic-kernel · error · KernelException

The proxy step can only handle 1 parameter object

Error message

The proxy step can only handle 1 parameter object

What it means

Thrown by LocalProxy.AssignStepFunctionParameterValues when message.Values contains more or fewer than exactly one entry. A proxy step wraps a single external operation and can only accept one parameter object per message; it does not aggregate multiple input parameters like a regular step does.

Source

Thrown at dotnet/src/Experimental/Process.LocalRuntime/LocalProxy.cs:42

    /// <param name="proxy">an instance of <see cref="KernelProcessProxy"/></param>
    /// <param name="kernel">An instance of <see cref="Kernel"/></param>
    internal LocalProxy(KernelProcessProxy proxy, Kernel kernel)
        : base(proxy, kernel)
    {
        this._proxy = proxy;
        this._logger = this._kernel.LoggerFactory?.CreateLogger(this._proxy.State.Name) ?? new NullLogger<LocalStep>();
    }

    internal override void AssignStepFunctionParameterValues(ProcessMessage message)
    {
        if (this._functions is null || this._inputs is null || this._initialInputs is null)
        {
            throw new KernelException("The step has not been initialized.").Log(this._logger);
        }

        if (message.Values.Count != 1)
        {
            throw new KernelException("The proxy step can only handle 1 parameter object").Log(this._logger);
        }

        var kvp = message.Values.Single();

        if (this._inputs.TryGetValue(message.FunctionName, out Dictionary<string, object?>? functionName) && functionName != null && functionName.TryGetValue(kvp.Key, out object? parameterName) && parameterName != null)
        {
            this._logger.LogWarning("Step {StepName} already has input for {FunctionName}.{Key}, it is being overwritten with a message from Step named '{SourceId}'.", this.Name, message.FunctionName, kvp.Key, message.SourceId);
        }

        if (!this._inputs.TryGetValue(message.FunctionName, out Dictionary<string, object?>? functionParameters))
        {
            this._inputs[message.FunctionName] = [];
            functionParameters = this._inputs[message.FunctionName];
        }

        if (this._proxy.ProxyMetadata != null && message.SourceEventId != null && this._proxy.ProxyMetadata.EventMetadata.TryGetValue(message.SourceEventId, out var metadata) && metadata != null)
        {
            functionParameters![kvp.Key] = KernelProcessProxyMessageFactory.CreateProxyMessage(this.ParentProcessId!, message.SourceEventId, metadata.TopicName, kvp.Value);

View on GitHub (pinned to c028a0c7dc)

Solutions

Ensure edges targeting a KernelProcessProxy step deliver exactly one value in the message.
If multiple values are needed, wrap them in a single composite object before sending.
Review the edge's OutputTarget (KernelProcessFunctionTarget) parameter mapping to confirm only one parameter is targeted.

Example fix

// before - proxy step receives multiple parameters
msg.Values = new Dictionary<string, object?> { ["a"] = val1, ["b"] = val2 };
// after - wrap into a single parameter object
msg.Values = new Dictionary<string, object?> { ["input"] = new { A = val1, B = val2 } };

Defensive patterns

Strategy: validation

Validate before calling

// Validate that edges targeting proxy steps deliver exactly one parameter
foreach (var edgeList in process.Edges.Values)
{
    foreach (var edge in edgeList)
    {
        if (edge.OutputTarget is KernelProcessFunctionTarget ft && proxyStepIds.Contains(ft.StepId))
        {
            // Ensure the function target maps only one parameter
            if (ft.ParameterNames is null || ft.ParameterNames.Count != 1) { /* warn or fix */ }
        }
    }
}

Prevention

Design proxy step edges to carry exactly one parameter value.
Wrap multiple values into a single composite object before sending to a proxy step.
Document that proxy steps accept only one parameter to guide edge configuration.

When it happens

Trigger: A ProcessMessage routed to a LocalProxy step contains a Values dictionary with a count other than 1. This happens when an edge targeting the proxy step maps multiple parameters, or when the message factory produces a multi-value message for a proxy target.

Common situations: Configuring an edge to a proxy step with multiple parameter mappings; sending a regular multi-parameter ProcessMessage to a proxy step; misunderstanding that proxy steps accept only a single opaque parameter object.

Related errors

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