What causes "The Map must be initialized before accessing the Name property." in microsoft/semantic-kernel?

Always call InitializeMapAsync with a valid DaprMapInfo before interacting with the map actor.

microsoft/semantic-kernel · error · KernelException

The Map must be initialized before accessing the Name proper

Error message

The Map must be initialized before accessing the Name property.

What it means

Thrown by the Name property getter on MapActor when _mapInfo is null. The map actor must be initialized via InitializeMapActor (called from InitializeMapAsync or OnActivateAsync when persisted state exists) before any code accesses the Name property. Accessing Name before initialization means the Dapr map actor has no map information loaded.

Source

Thrown at dotnet/src/Experimental/Process.Runtime.Dapr/Actors/MapActor.cs:78

    /// rather than ToKernelProcessAsync when extracting the state.
    /// </summary>
    /// <returns>A <see cref="Task{T}"/> where T is <see cref="KernelProcess"/></returns>
    public override Task<DaprStepInfo> ToDaprStepInfoAsync() => Task.FromResult<DaprStepInfo>(this._mapInfo!);

    protected override async Task OnActivateAsync()
    {
        var existingMapInfo = await this.StateManager.TryGetStateAsync<DaprMapInfo>(DaprProcessMapStateName).ConfigureAwait(false);
        if (existingMapInfo.HasValue)
        {
            this.ParentProcessId = await this.StateManager.GetStateAsync<string>(ActorStateKeys.StepParentProcessId).ConfigureAwait(false);
            this.InitializeMapActor(existingMapInfo.Value, this.ParentProcessId);
        }
    }

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

    #endregion

    /// <summary>
    /// Handles a <see cref="ProcessMessage"/> that has been sent to the map.
    /// </summary>
    /// <param name="message">The message to map.</param>
    internal override async Task HandleMessageAsync(ProcessMessage message)
    {
        // Initialize the current operation
        (IEnumerable inputValues, KernelProcess mapOperation, string startEventId) = this._map!.Initialize(message, this._logger);

        List<Task> mapOperations = [];
        foreach (var value in inputValues)
        {
            KernelProcess mapProcess = mapOperation with { State = mapOperation.State with { Id = $"{this.Name}-{mapOperations.Count}-{Guid.NewGuid():N}" } };
            DaprKernelProcessContext processContext = new(mapProcess);
            Task processTask =

View on GitHub (pinned to c028a0c7dc)

Solutions

Always call InitializeMapAsync with a valid DaprMapInfo before interacting with the map actor.
Verify the Dapr state store is accessible so that OnActivateAsync can restore persisted map info on reactivation.
Ensure the map actor id is unique and initialized once per logical map.

Example fix

// before - accessing map actor before initialization
var name = mapActor.Name;
// after - initialize first
await mapActor.InitializeMapAsync(mapInfo, parentProcessId).ConfigureAwait(false);
var name = mapActor.Name;

Defensive patterns

Strategy: validation

Validate before calling

// Before accessing map actor properties, ensure initialization has completed
await mapActor.InitializeMapAsync(mapInfo, parentProcessId).ConfigureAwait(false);
// Only access Name/HandleMessage after initialization

Prevention

Always call InitializeMapAsync before any other interaction with the map actor.
Verify the Dapr state store is accessible so persisted state survives actor re-activation.
Use unique actor ids per logical map to avoid collision with uninitialized actors.

When it happens

Trigger: Code accesses MapActor.Name before InitializeMapAsync has been called, or the actor was activated from scratch (no persisted state) and OnActivateAsync found no existing DaprMapInfo to restore. Any framework code or logging that touches Name during early lifecycle triggers this.

Common situations: Forgetting to call InitializeMapAsync when creating a map step; a Dapr actor activation race where Name is accessed before OnActivateAsync completes; persisted state was lost or corrupted so OnActivateAsync skips initialization; the map actor id is reused without prior initialization.

Related errors

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