microsoft/semantic-kernel · error · KernelException

Unable to restore channel: invalid state.

Error message

Unable to restore channel: invalid state.

What it means

Thrown by AggregatorAgent.RestoreChannelAsync when JsonSerializer.Deserialize<AgentChatState> returns null after deserializing the provided channelState string. The AggregatorAgent uses channels backed by an AgentChat; when the AgentChat is rehydrated from serialized state, the JSON must deserialize to a non-null AgentChatState object.

Source

Thrown at dotnet/src/Agents/Abstractions/AggregatorAgent.cs:100

        this.Logger.LogAggregatorAgentCreatingChannel(nameof(CreateChannelAsync), nameof(AggregatorChannel));

        AgentChat chat = chatProvider.Invoke();
        AggregatorChannel channel = new(chat);

        this.Logger.LogAggregatorAgentCreatedChannel(nameof(CreateChannelAsync), nameof(AggregatorChannel), this.Mode, chat.GetType());

        return Task.FromResult<AgentChannel>(channel);
    }

    /// <inheritdoc/>
    protected internal override async Task<AgentChannel> RestoreChannelAsync(string channelState, CancellationToken cancellationToken)
    {
        this.Logger.LogOpenAIAssistantAgentRestoringChannel(nameof(CreateChannelAsync), nameof(AggregatorChannel));

        AgentChat chat = chatProvider.Invoke();
        AgentChatState agentChatState =
            JsonSerializer.Deserialize<AgentChatState>(channelState) ??
            throw new KernelException("Unable to restore channel: invalid state.");

        await chat.DeserializeAsync(agentChatState).ConfigureAwait(false); ;
        AggregatorChannel channel = new(chat);

        this.Logger.LogOpenAIAssistantAgentRestoredChannel(nameof(CreateChannelAsync), nameof(AggregatorChannel));

        return channel;
    }
}

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Ensure the same package version serializes and restores channel state.
2. Inspect the channelState string value in a debugger to verify it is valid JSON and not the literal "null".
3. Avoid manually constructing or caching channel state; let the framework manage serialization.
4. If using custom persistence, verify the round-trip: serialize then deserialize locally before persisting.

try
{
    // multi-agent chat with AggregatorAgent
    await chat.InvokeAsync(ct);
}
catch (KernelException ex) when (ex.Message.Contains("Unable to restore channel: invalid state"))
{
    // Channel state is corrupt or version-mismatched; recreate the chat
    _logger.LogError(ex, "Channel state restoration failed; recreating chat.");
}

When it happens

Trigger: The framework calls RestoreChannelAsync with a channelState string that deserializes to null — e.g., the literal JSON token "null", a corrupt/truncated string, or a state blob produced by a mismatched serialization version. This happens during multi-agent channel synchronization when an AggregatorAgent's channel needs to be restored from a previously serialized key.

Common situations: Version mismatch between the code that serialized the channel state and the code that restores it. Manual or incorrect channel state injection. Memory corruption or truncation of the state string in distributed scenarios. Upgrading the SDK across a breaking change to AgentChatState serialization.

Related errors

• Unexpected failure broadcasting to channel: {channelRef.Chan
• The specified function {function.Id} is not available in the
• The message could not be added to the thread due to an error
• Unable to transform output to {typeof(TOutput)}.
• Unable to transform result into {typeof(TOutput).Name}

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