github/copilot-sdk · error · JsonException

Unknown MessageSource value

Error message

Unknown MessageSource value: {value}

What it means

The MessageSource converter parses the string via GeneratedStringEnumJson.ReadValue, then maps it: "user" → User, "system" → System, anything starting with "agent-" → a dynamic MessageSource. Any other value throws this JsonException listing the unrecognized value.

Solutions

1. Use one of the supported values: "user", "system", or an "agent-<name>" string.
2. Upgrade the SDK to a version that recognizes the new MessageSource value.
3. Check the API changelog for renamed source identifiers.
4. Catch JsonException and fall back to a raw/generic source representation if the library offers one.

Example fix

// before
{"source": "assistant"}
// after
{"source": "agent-assistant"} // or "user"/"system"

var s = doc.RootElement.GetProperty("source").GetString();
var known = s == "user" || s == "system" || (s?.StartsWith("agent-") ?? false);
if (!known) throw new InvalidDataException($"unsupported MessageSource: {s}");

static bool IsKnownMessageSource(string s) => s is "user" or "system" || s.StartsWith("agent-");

try { msg = JsonSerializer.Deserialize<Message>(json); }
catch (JsonException ex) { log.LogWarning(ex, "unknown MessageSource '{V}' — upgrade SDK or normalize value", rawValue); }

When it happens

Trigger: Deserializing JSON like `"source": "assistant"` or `"source": "tool"` — a string that is neither "user", "system", nor prefixed "agent-".

Common situations: New source kinds introduced server-side that the local SDK version does not know; typos in hand-written JSON; other SDKs emitting different source identifiers.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 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/77429786c9aca36e. Report an issue: GitHub.

Appendix: source

Thrown at dotnet/src/Types.cs:2178

        return new("agent-" + id);
    }

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

    /// <summary>Converts message sources to and from their wire strings.</summary>
    public sealed class Converter : JsonConverter<MessageSource>
    {
        /// <inheritdoc/>
        public override MessageSource Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
        {
            var value = GeneratedStringEnumJson.ReadValue(ref reader, typeToConvert);
            return value switch
            {
                "user" => User,
                "system" => System,
                _ when value.StartsWith("agent-", StringComparison.Ordinal) => new MessageSource(value),
                _ => throw new JsonException($"Unknown MessageSource value: {value}")
            };
        }

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

/// <summary>
/// Specifies the operation to perform on a system message section.
/// </summary>
[JsonConverter(typeof(JsonStringEnumConverter<SectionOverrideAction>))]
public enum SectionOverrideAction
{
    /// <summary>Replace the section content entirely.</summary>
    [JsonStringEnumMemberName("replace")]
    Replace,

View on GitHub (pinned to cd8cf15dc3)