microsoft/semantic-kernel · error · KernelException

The Process must be initialized before accessing the Name pr

Error message

The Process must be initialized before accessing the Name property.

What it means

The ProcessActor.Name property getter throws this KernelException when the internal _process field (a DaprProcessInfo) is null. The _process field is only assigned inside InitializeProcessActorAsync, so any access to Name before that call completes will fail. Name is used internally by logging, ToDaprProcessInfoAsync, ScopedEvent, and other paths, so the throw can surface indirectly.

Source

Thrown at dotnet/src/Experimental/Process.Runtime.Dapr/Actors/ProcessActor.cs:187

    protected override async Task OnActivateAsync()
    {
        var existingProcessInfo = await this.StateManager.TryGetStateAsync<DaprProcessInfo>(ActorStateKeys.ProcessInfoState).ConfigureAwait(false);
        if (existingProcessInfo.HasValue)
        {
            this.ParentProcessId = await this.StateManager.GetStateAsync<string>(ActorStateKeys.StepParentProcessId).ConfigureAwait(false);
            string? eventProxyStepId = null;
            if (await this.StateManager.ContainsStateAsync(ActorStateKeys.EventProxyStepId).ConfigureAwait(false))
            {
                eventProxyStepId = await this.StateManager.GetStateAsync<string>(ActorStateKeys.EventProxyStepId).ConfigureAwait(false);
            }
            await this.InitializeProcessActorAsync(existingProcessInfo.Value, this.ParentProcessId, eventProxyStepId).ConfigureAwait(false);
        }
    }

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

    #endregion

    /// <summary>
    /// Handles a <see cref="ProcessMessage"/> that has been sent to the process. This happens only in the case
    /// of a process (this one) running as a step within another process (this one's parent). In this case the
    /// entire sub-process should be executed within a single superstep.
    /// </summary>
    /// <param name="message">The message to process.</param>
    internal override async Task HandleMessageAsync(ProcessMessage message)
    {
        if (string.IsNullOrWhiteSpace(message.TargetEventId))
        {
            throw new KernelException("Internal Process Error: The target event id must be specified when sending a message to a step.").Log(this._logger);
        }

        string eventId = message.TargetEventId!;
        if (this._outputEdges!.TryGetValue(eventId, out List<KernelProcessEdge>? edges) && edges is not null)

View on GitHub (pinned to c028a0c7dc)

Solutions

Ensure InitializeProcessAsync (which delegates to InitializeProcessActorAsync and sets _process) is awaited before calling GetProcessInfoAsync, StartAsync, or any other method that reads the process name.
Verify that the Dapr actor state store contains ActorStateKeys.ProcessInfoState for re-activated actors, confirming the process was previously initialized and its state persisted.
Check that the actor proxy is targeting the correct actor ID so that persisted state, if it exists, is found by OnActivateAsync.

Example fix

// before
var proxy = actorProxyFactory.CreateActorProxy<IProcess>(actorId, nameof(ProcessActor));
var info = await proxy.GetProcessInfoAsync(); // throws if not initialized

// after
var proxy = actorProxyFactory.CreateActorProxy<IProcess>(actorId, nameof(ProcessActor));
await proxy.InitializeProcessAsync(processInfo, parentProcessId: null); // sets _process
var info = await proxy.GetProcessInfoAsync();

Defensive patterns

Strategy: validation

Validate before calling

// Before accessing process info or starting, verify initialization by attempting GetProcessInfoAsync
// in a try-catch, or track initialization externally:
bool isInitialized = false;
try
{
    await processProxy.InitializeProcessAsync(processInfo, parentProcessId);
    isInitialized = true;
}
catch { /* handle */ }

if (isInitialized)
{
    var info = await processProxy.GetProcessInfoAsync();
}

Try / catch

try
{
    var info = await processProxy.GetProcessInfoAsync();
}
catch (KernelException ex) when (ex.Message.Contains("The Process must be initialized"))
{
    // Process not initialized — call InitializeProcessAsync first
    logger.LogWarning("Process actor not initialized. Call InitializeProcessAsync before use.");
}

Prevention

Always call and await InitializeProcessAsync before any other method on a ProcessActor proxy.
For re-activated actors, verify the Dapr state store contains ActorStateKeys.ProcessInfoState.
Wrap process-actor initialization in a helper that prevents usage before initialization completes.

When it happens

Trigger: Calling GetProcessInfoAsync(), ToDaprStepInfoAsync(), or any method that touches this.Name on a ProcessActor that was never initialized via InitializeProcessAsync(). Also occurs if OnActivateAsync finds no persisted ProcessInfoState in the Dapr state store (e.g. first activation with no prior save) and a subsequent method reads Name before InitializeProcessActorAsync runs.

Common situations: Process actor activated from scratch with no persisted state, a race where a method runs before initialization completes, or calling GetProcessInfoAsync on a freshly created process actor proxy that has not had InitializeProcessAsync invoked yet.

Related errors

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