microsoft/semantic-kernel · error · KernelException

Unable to deserialize ProcessMessage queue.

Error message

Unable to deserialize ProcessMessage queue.

What it means

Thrown when JSON deserialization of a ProcessMessage container yields null. Messages are wrapped in a MessageContainer; a null result means the JSON could not be deserialized into that shape.

Source

Thrown at dotnet/src/Experimental/Process.Runtime.Dapr/Serialization/ProcessMessageSerializer.cs:41

        MessageContainer containedMessage = new(TypeInfo.GetAssemblyQualifiedType(processMessage.TargetEventData), typeMap, processMessage);
        return JsonSerializer.Serialize(containedMessage);
    }

    /// <summary>
    /// Deserialize a list of JSON messages into a list of <see cref="ProcessMessage"/> objects.
    /// </summary>
    /// <exception cref="KernelException">If any message fails deserialization</exception>
    public static IList<ProcessMessage> ToProcessMessages(this IEnumerable<string> jsonMessages)
    {
        return Deserialize().ToArray();

        IEnumerable<ProcessMessage> Deserialize()
        {
            foreach (string json in jsonMessages)
            {
                MessageContainer containedMessage =
                    JsonSerializer.Deserialize<MessageContainer>(json) ??
                    throw new KernelException($"Unable to deserialize {nameof(ProcessMessage)} queue.");

                yield return Process(containedMessage);
            }
        }
    }

    private static ProcessMessage Process(MessageContainer messageContainer)
    {
        ProcessMessage processMessage = messageContainer.Message;

        if (processMessage.Values.Count == 0)
        {
            return processMessage;
        }

        processMessage =
            processMessage with
            {

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Examine the failing JSON entry to confirm it has the expected MessageContainer shape with a valid Message field.
2. Ensure producers and consumers share the same ProcessMessage serialization version.
3. Purge corrupted entries or implement tolerant handling that logs and skips bad messages.
4. Pre-validate that each JSON string is a non-null object before deserialization.

var valid = jsonMessages.Where(j => !string.IsNullOrWhiteSpace(j) && j.Trim() != "null").ToList();
var messages = valid.ToProcessMessages();

public static bool IsValidMessageJson(string json) =>
    !string.IsNullOrWhiteSpace(json) && json.TrimStart().StartsWith("{");

try
{
    var messages = jsonMessages.ToProcessMessages();
}
catch (KernelException ex) when (ex.Message.Contains("Unable to deserialize ProcessMessage queue"))
{
    _logger.LogError(ex, "Malformed message JSON in batch.");
    throw;
}

When it happens

Trigger: ProcessMessageSerializer.ToProcessMessages iterates JSON strings and deserializes each into MessageContainer; a null result for any entry raises this exception before processing the message.

Common situations: Corrupted message entries in the Dapr message buffer, schema/version drift in ProcessMessage, or a payload written by a different serializer.

Related errors

• Unable to deserialize KernelProcessEvent queue.
• Unable to deserialize ProcessEvent queue.
• Data persisted without type information.
• Unable to read state from map with name '{this.State.Name}'
• Unable to read state from process with name '{this.State.Nam

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