microsoft/semantic-kernel · error · KernelException

The Step must be initialized before accessing the Name prope

Error message

The Step must be initialized before accessing the Name property.

What it means

StepActor.Name returns this._stepInfo?.State.Name, throwing if _stepInfo is null. The _stepInfo field is assigned in InitializeStep (called by InitializeStepAsync or OnActivateAsync). Accessing Name before initialization completes triggers this KernelException. Name is used internally by logging and error messages.

Source

Thrown at dotnet/src/Experimental/Process.Runtime.Dapr/Actors/StepActor.cs:211

                eventProxyStepId = await this.StateManager.GetStateAsync<string>(ActorStateKeys.EventProxyStepId).ConfigureAwait(false);
            }
            this.InitializeStep(existingStepInfo.Value, parentProcessId, eventProxyStepId);

            // Load the persisted incoming messages
            var incomingMessages = await this.StateManager.TryGetStateAsync<Queue<ProcessMessage>>(ActorStateKeys.StepIncomingMessagesState).ConfigureAwait(false);
            if (incomingMessages.HasValue)
            {
                this._incomingMessages = incomingMessages.Value;
            }
        }
    }

    #endregion

    /// <summary>
    /// The name of the step.
    /// </summary>
    protected virtual string Name => this._stepInfo?.State.Name ?? throw new KernelException("The Step must be initialized before accessing the Name property.").Log(this._logger);

    /// <summary>
    /// Emits an event from the step.
    /// </summary>
    /// <param name="processEvent">The event to emit.</param>
    /// <returns>A <see cref="ValueTask"/></returns>
    public ValueTask EmitEventAsync(KernelProcessEvent processEvent) => this.EmitEventAsync(ProcessEvent.Create(processEvent, this._eventNamespace!));

    // TODO: this can be moved to shared runtime code, looks almost/same to localRuntime implementation
    internal virtual 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);
        }

        // Add the message values to the inputs for the function
        foreach (var kvp in message.Values)

View on GitHub (pinned to c028a0c7dc)

Solutions

Ensure InitializeStepAsync is awaited before invoking any method on the step actor proxy.
Verify that the Dapr actor state store has ActorStateKeys.StepInfoState for re-activated step actors.
If the actor is freshly created, always call InitializeStepAsync first before SendAsync, PrepareIncomingMessagesAsync, or ProcessIncomingMessagesAsync.

Example fix

// before
var stepProxy = factory.CreateActorProxy<IStep>(stepId, nameof(StepActor));
await stepProxy.PrepareIncomingMessagesAsync(); // throws if not initialized

// after
var stepProxy = factory.CreateActorProxy<IStep>(stepId, nameof(StepActor));
await stepProxy.InitializeStepAsync(stepInfo, parentProcessId);
await stepProxy.PrepareIncomingMessagesAsync();

Defensive patterns

Strategy: validation

Validate before calling

// Ensure InitializeStepAsync is called before any other operation:
await stepActor.InitializeStepAsync(stepInfo, parentProcessId);
// Only then proceed with message processing or state extraction:
await stepActor.PrepareIncomingMessagesAsync();

Try / catch

try
{
    var info = await stepActor.ToDaprStepInfoAsync();
}
catch (KernelException ex) when (ex.Message.Contains("Step must be initialized"))
{
    logger.LogError("Step actor not initialized. Call InitializeStepAsync first.");
}

Prevention

Call and await InitializeStepAsync before any other method on a step actor proxy.
Verify the Dapr state store has StepInfoState for re-activated actors.
Track initialization state externally when orchestrating multiple step actors.

When it happens

Trigger: Any code path that reads this.Name before InitializeStepAsync (or OnActivateAsync from persisted state) has set _stepInfo. This includes EmitEventAsync logging, HandleMessageAsync logging, and ToDaprStepInfoAsync.

Common situations: A step actor proxy is created and a method is called before InitializeStepAsync. The actor is re-activated but no persisted StepInfoState exists in the Dapr state store. A race condition where a message arrives before initialization.

Related errors

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