github/copilot-sdk · error · JsonException

Expected string for SystemMessageSection.

Error message

Expected string for SystemMessageSection.

What it means

Thrown by SystemMessageSection's JsonConverter during deserialization when the JSON token for a SystemMessageSection value is not a string. SystemMessageSection is a string-backed, case-insensitive strongly typed value, so only JSON strings are accepted; a number, object, array, or null in that position triggers this. The faulting input is malformed wire data or hand-built JSON rather than caller arguments.

Solutions

1. Send a string value for the field.
2. Confirm the server schema still defines the field as a string.
3. Make the property nullable if the section can be absent.
4. Catch JsonException and log the token type/position to find the field.

Example fix

// before
{"section": 42}
// after
{"section": "overview"}

if (doc.RootElement.GetProperty("section").ValueKind != JsonValueKind.String)
    throw new InvalidDataException("section must be a string");

static bool IsJsonString(JsonElement e) => e.ValueKind == JsonValueKind.String;

try { sm = JsonSerializer.Deserialize<SystemMessage>(json); }
catch (JsonException ex) { log.LogError(ex, "SystemMessageSection token was not a string"); }

When it happens

Trigger: Deserializing JSON where a system message section field is a number, object, array, or null, e.g. `"section": {}` where `"section": "intro"` is expected.

Common situations: Schema drift between client and server; hand-written JSON mistakes; serialization of the field by a different language runtime with different typing.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Failed to deserialize permission request
• Expected a string token when reading
• Expected a non-empty string token when reading
• Expected string for ToolBinaryResultType.
• ToolBinaryResultType value cannot be null.

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/8aeda4cf71c6dee8. Report an issue: GitHub.

Appendix: source

Thrown at dotnet/src/Types.cs:2312

    /// <inheritdoc/>
    public bool Equals(SystemMessageSection other) => string.Equals(Value, other.Value, StringComparison.OrdinalIgnoreCase);

    /// <inheritdoc/>
    public override int GetHashCode() => StringComparer.OrdinalIgnoreCase.GetHashCode(Value);

    /// <inheritdoc/>
    public override string ToString() => Value;

    /// <summary>Provides a <see cref="JsonConverter{SystemMessageSection}"/> for serializing <see cref="SystemMessageSection"/> instances.</summary>
    [EditorBrowsable(EditorBrowsableState.Never)]
    public sealed class Converter : JsonConverter<SystemMessageSection>
    {
        /// <inheritdoc/>
        public override SystemMessageSection Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
        {
            if (reader.TokenType != JsonTokenType.String)
            {
                throw new JsonException("Expected string for SystemMessageSection.");
            }

            var value = reader.GetString();
            if (value is null)
            {
                throw new JsonException("SystemMessageSection value cannot be null.");
            }

            return new SystemMessageSection(value);
        }

        /// <inheritdoc/>
        public override void Write(Utf8JsonWriter writer, SystemMessageSection value, JsonSerializerOptions options) =>
            writer.WriteStringValue(value.Value);

        /// <inheritdoc/>
        public override SystemMessageSection ReadAsPropertyName(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options) =>
            new(reader.GetString()!);

View on GitHub (pinned to cd8cf15dc3)