microsoft/semantic-kernel · error · KernelException

Unable to deserialize KernelProcessEvent queue.

Error message

Unable to deserialize KernelProcessEvent queue.

What it means

Thrown when JSON deserialization of a single KernelProcessEvent produces null. The serializer wraps each event in an EventContainer<T> and expects a non-null result; a null indicates malformed JSON or a payload that does not map to KernelProcessEvent.

Source

Thrown at dotnet/src/Experimental/Process.Runtime.Dapr/Serialization/KernelProcessEventSerializer.cs:50

        IEnumerable<KernelProcessEvent> Deserialize()
        {
            foreach (string json in jsonEvents)
            {
                yield return json.ToKernelProcessEvent();
            }
        }
    }

    /// <summary>
    /// Deserialize a list of JSON events into a list of <see cref="KernelProcessEvent"/> objects.
    /// </summary>
    /// <exception cref="KernelException">If any event fails deserialization</exception>
    public static KernelProcessEvent ToKernelProcessEvent(this string jsonEvent)
    {
        EventContainer<KernelProcessEvent> eventContainer =
            JsonSerializer.Deserialize<EventContainer<KernelProcessEvent>>(jsonEvent) ??
            throw new KernelException($"Unable to deserialize {nameof(KernelProcessEvent)} queue.");
        return eventContainer.Payload with { Data = TypeInfo.ConvertValue(eventContainer.DataTypeName, eventContainer.Payload.Data) };
    }
}

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Inspect the raw JSON string being deserialized to confirm it is a valid EventContainer payload, not a literal null.
2. Ensure the producer writing KernelProcessEvent entries uses the same serialization format and version as the reader.
3. Filter or purge corrupted entries from the event queue if they cannot be recovered.
4. Add a pre-check that the JSON is non-empty and not the literal token 'null' before calling ToKernelProcessEvent.

// Pre-validate the JSON is a non-null object before deserializing
if (string.IsNullOrWhiteSpace(jsonEvent) || jsonEvent.Trim() == "null")
    throw new InvalidOperationException("Cannot deserialize a null KernelProcessEvent entry.");

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

try
{
    var evt = jsonEvent.ToKernelProcessEvent();
}
catch (KernelException ex) when (ex.Message.Contains("Unable to deserialize KernelProcessEvent queue"))
{
    _logger.LogError(ex, "Malformed event JSON; quarantining entry.");
    // optionally skip or move to a dead-letter store
}

When it happens

Trigger: KernelProcessEventSerializer.ToKernelProcessEvent deserializes a JSON string into EventContainer<KernelProcessEvent>; if the result is null (e.g., JSON literal "null" or incompatible payload), the exception fires.

Common situations: Corrupted entries in the Dapr event queue, a payload written by an incompatible serializer/version, or a null token persisted in place of a real event. Often surfaces during process initialization when replaying queued events.

Related errors

• Unable to deserialize ProcessEvent queue.
• Unable to deserialize ProcessMessage 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/dfd279f4609ccb9f. Report an issue: GitHub.