tui-cs/Terminal.Gui · error · JsonException

Unexpected color name: {colorString}.

Error message

Unexpected color name: {colorString}.

What it means

Thrown by ColorJsonConverter.Read: the JSON token was a string, but ColorStrings.TryParseNamedColor and Color.TryParse both failed. The string is neither a W3C named color nor a parseable hex/rgb()/rgba() format. The supported formats are documented on the converter: #RGB, #RRGGBB, #ARGB, #AARRGGBB, rgb(r,g,b), rgb(r,g,b,a), rgba(r,g,b), rgba(r,g,b,a), or a W3C name.

Source

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

    public override Color Read (ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        // Check if the value is a string
        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. Use a W3C named color (e.g. "Red", "BrightBlue") or a hex form starting with # (#FF0000).
2. If you need rgb/rgba, use the exact "rgb(r,g,b)" / "rgba(r,g,b,a)" syntax with commas.
3. Confirm the spelling against ColorStrings / the W3C list.

Example fix

// before
"Foreground": "reed"
// after
"Foreground": "Red"

string colorStr = reader.GetString ()!;
if (!ColorStrings.TryParseNamedColor (colorStr, out _)
    && !Color.TryParse (colorStr, null, out _))
    throw new FormatException ($"Unrecognized color: {colorStr}");

static bool IsValidColorString (string s) =>
    ColorStrings.TryParseNamedColor (s, out _) || Color.TryParse (s, null, out _);

try { ConfigurationManager.Apply (); }
catch (JsonException ex) when (ex.Message.Contains ("Unexpected color name"))
{ /* correct the color string */ }

When it happens

Trigger: A Color value like "reed", "#GGGGGG", "hsl(0,100%,50%)", "255,0,0", or "red1" — any string the parser cannot map.

Common situations: Typo in a color name; using a CSS format Terminal.Gui does not support (hsl, named-with-suffix like "darkred" if not in the W3C set the parser knows); hex string missing the leading #; non-ASCII or quoted-with-smart-quotes.

Related errors

• Unexpected token when parsing Color: {reader.TokenType}
• {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/6a7f821ba21292a9. Report an issue: GitHub.