{"record":{"id":"88c3a0a4bbd4e973","repo":"microsoft/semantic-kernel","slug":"unable-to-restore-channel-invalid-state","errorCode":null,"errorMessage":"Unable to restore channel: invalid state.","messagePattern":"Unable to restore channel: invalid state\\.","errorType":"exception","errorClass":"KernelException","httpStatus":null,"severity":"error","filePath":"dotnet/src/Agents/Abstractions/AggregatorAgent.cs","lineNumber":100,"sourceCode":"        this.Logger.LogAggregatorAgentCreatingChannel(nameof(CreateChannelAsync), nameof(AggregatorChannel));\n\n        AgentChat chat = chatProvider.Invoke();\n        AggregatorChannel channel = new(chat);\n\n        this.Logger.LogAggregatorAgentCreatedChannel(nameof(CreateChannelAsync), nameof(AggregatorChannel), this.Mode, chat.GetType());\n\n        return Task.FromResult<AgentChannel>(channel);\n    }\n\n    /// <inheritdoc/>\n    protected internal override async Task<AgentChannel> RestoreChannelAsync(string channelState, CancellationToken cancellationToken)\n    {\n        this.Logger.LogOpenAIAssistantAgentRestoringChannel(nameof(CreateChannelAsync), nameof(AggregatorChannel));\n\n        AgentChat chat = chatProvider.Invoke();\n        AgentChatState agentChatState =\n            JsonSerializer.Deserialize<AgentChatState>(channelState) ??\n            throw new KernelException(\"Unable to restore channel: invalid state.\");\n\n        await chat.DeserializeAsync(agentChatState).ConfigureAwait(false); ;\n        AggregatorChannel channel = new(chat);\n\n        this.Logger.LogOpenAIAssistantAgentRestoredChannel(nameof(CreateChannelAsync), nameof(AggregatorChannel));\n\n        return channel;\n    }\n}\n","sourceCodeStart":82,"sourceCodeEnd":110,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/dotnet/src/Agents/Abstractions/AggregatorAgent.cs#L82-L110","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the same package version serializes and restores channel state.","Inspect the channelState string value in a debugger to verify it is valid JSON and not the literal \"null\".","Avoid manually constructing or caching channel state; let the framework manage serialization.","If using custom persistence, verify the round-trip: serialize then deserialize locally before persisting."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try\n{\n    // multi-agent chat with AggregatorAgent\n    await chat.InvokeAsync(ct);\n}\ncatch (KernelException ex) when (ex.Message.Contains(\"Unable to restore channel: invalid state\"))\n{\n    // Channel state is corrupt or version-mismatched; recreate the chat\n    _logger.LogError(ex, \"Channel state restoration failed; recreating chat.\");\n}","preventionTips":["Keep serialization and deserialization code on the same SDK version.","Do not persist channel state strings across deployments with different package versions.","Let the framework serialize and restore channel state; avoid manual state manipulation."],"tags":["aggregator-agent","channel","serialization","kernalexception"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}