microsoft/autogen · error · JsonException

Exception of type 'System.Text.Json.JsonException' was throw

Error message

Exception of type 'System.Text.Json.JsonException' was thrown.

What it means

In OpenAIMessageConverter.Read, a message with role 'system' that fails to deserialize into OpenAISystemMessage (Deserialize returns null or its required members are missing) produces a bare JsonException. This converter fronts the OpenAI-compatible WebAPI endpoint, so the exception surfaces as HTTP deserialization failure of the request body.

Source

Thrown at dotnet/src/AutoGen.WebAPI/OpenAI/Converter/OpenAIMessageConverter.cs:22

using System;
using System.Text.Json;
using System.Text.Json.Serialization;

namespace AutoGen.WebAPI.OpenAI.DTO;

internal class OpenAIMessageConverter : JsonConverter<OpenAIMessage>
{
    public override OpenAIMessage Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        using JsonDocument document = JsonDocument.ParseValue(ref reader);
        var root = document.RootElement;
        var role = root.GetProperty("role").GetString();
        var contentDocument = root.GetProperty("content");
        var isContentDocumentString = contentDocument.ValueKind == JsonValueKind.String;
        switch (role)
        {
            case "system":
                return JsonSerializer.Deserialize<OpenAISystemMessage>(root.GetRawText()) ?? throw new JsonException();
            case "user" when isContentDocumentString:
                return JsonSerializer.Deserialize<OpenAIUserMessage>(root.GetRawText()) ?? throw new JsonException();
            case "user" when !isContentDocumentString:
                return JsonSerializer.Deserialize<OpenAIUserMultiModalMessage>(root.GetRawText()) ?? throw new JsonException();
            case "assistant":
                return JsonSerializer.Deserialize<OpenAIAssistantMessage>(root.GetRawText()) ?? throw new JsonException();
            case "tool":
                return JsonSerializer.Deserialize<OpenAIToolMessage>(root.GetRawText()) ?? throw new JsonException();
            default:
                throw new JsonException();
        }
    }

    public override void Write(Utf8JsonWriter writer, OpenAIMessage value, JsonSerializerOptions options)
    {
        switch (value)
        {
            case OpenAISystemMessage systemMessage:

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Send system messages as {"role":"system","content":"your system prompt"} with string content
2. Validate the request body against the OpenAI chat-completions schema before sending
3. Catch JsonException in ASP.NET pipeline and return 400 with a meaningful message instead of a 500
4. Check that no intermediate layer (gateway/middleware) rewrites or strips the content field

Example fix

// before
{"role":"system","content":null}

// after
{"role":"system","content":"You are a helpful assistant."}

// client-side pre-validation of system messages
bool IsValidSystemMessage(JsonElement m) =>
    m.GetProperty("role").GetString() == "system"
    && m.GetProperty("content").ValueKind == JsonValueKind.String;

static bool IsSystemMessage(JsonElement m) =>
    m.TryGetProperty("role", out var r) && r.GetString() == "system";

try { await httpClient.PostAsJsonAsync("/v1/chat/completions", body); }
catch (JsonException ex)
{
    // server-side: map to 400 with position info
    return BadRequest($"Malformed system message at position {ex.LineNumber}:{ex.BytePositionInLine}");
}

When it happens

Trigger: POSTing to the WebAPI chat-completions endpoint a JSON message with "role":"system" whose payload does not match OpenAISystemMessage's expected shape (e.g. missing required properties, wrong casing without the matching serializer options).

Common situations: Third-party clients sending system messages with extra/absent fields, a proxy reformatting the body, or a payload where 'content' is null instead of a string.

Related errors

• Unsupported reply content type
• Unsupported message type {m.GetType()}
• Value was null.
• Failed to deserialize response
• Value cannot be null. (Parameter 'Content')

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/b468681c4fc22d7d. Report an issue: GitHub.