tui-cs/Terminal.Gui · error · JsonException

Unexpected token when parsing Color: {reader.TokenType}

Error message

Unexpected token when parsing Color: {reader.TokenType}

What it means

Thrown by ColorJsonConverter.Read when the JSON token for a Color value is not a string at all (e.g. Number, StartObject, True, Null). Color is serialized and expected as a string token; any other token type is rejected before parsing is attempted.

Source

Thrown at Terminal.Gui/Configuration/ColorJsonConverter.cs:55

        if (reader.TokenType == JsonTokenType.String)
        {
            // Get the color string
            ReadOnlySpan<char> colorString = reader.GetString ();

            if (ColorStrings.TryParseNamedColor (colorString, out Color namedColor))
            {
                return namedColor;
            }

            if (Color.TryParse (colorString, null, out Color parsedColor))
            {
                return parsedColor;
            }

            throw new JsonException ($"Unexpected color name: {colorString}.");
        }

        throw new JsonException ($"Unexpected token when parsing Color: {reader.TokenType}");
    }

    public override void Write (Utf8JsonWriter writer, Color value, JsonSerializerOptions options)
    {
        writer.WriteStringValue (value.ToString ());
    }
}

View on GitHub (pinned to 2e47b11478)

Solutions

1. Provide the color as a JSON string ("Red", "#FF0000", "rgb(255,0,0)").
2. If your tool emits objects/numbers, transform them to the string form before loading.
3. Remove the null entry — omit the key entirely instead of setting null.

Example fix

// before
"Background": 0
// after
"Background": "Black"

if (el.ValueKind != JsonValueKind.String)
    throw new FormatException ($"Color must be a string token, was {el.ValueKind}");

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

try { ConfigurationManager.Apply (); }
catch (JsonException ex) when (ex.Message.Contains ("Unexpected token when parsing Color"))
{ /* convert the non-string color to a string form */ }

When it happens

Trigger: "Foreground": 255, or "Foreground": { "R": 255 }, or "Foreground": null, or "Foreground": [255,0,0].

Common situations: An exporter that serializes Color as a numeric code or RGB object; a config that uses null to mean "default"; copy-paste of an object form from a different theming system.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Unexpected color name: {colorString}.
• {propertyName}: Unexpected token when parsing Attribute: {re
• {propertyName}: Expected a string value.
• Expected a valid text style value.
• {propertyName}: Unknown Attribute property .

AI-assisted analysis of tui-cs/Terminal.Gui@2e47b11478 (2026-08-13). Data as JSON: /api/errors/ecd6ad67bef1d94d. Report an issue: GitHub.