tui-cs/Terminal.Gui · error · ColorParseException

Color hex string {hexString} was not in a supported format

Error message

Color hex string {hexString} was not in a supported format

What it means

Thrown by the hex sub-switch of Color.Parse when the input begins with '#' but does not match #RGB, #ARGB, #RRGGBB, or #AARRGGBB, or when its characters after '#' are not all valid ASCII hex digits. The message interpolates the offending hexString so you can see exactly what failed. It is a ColorParseException (FormatException).

Source

Thrown at Terminal.Gui/Drawing/Color/Color.Formatting.cs:327

                        byte.Parse ([r1Char, r2Char], NumberStyles.HexNumber),
                        byte.Parse ([g1Char, g2Char], NumberStyles.HexNumber),
                        byte.Parse ([b1Char, b2Char], NumberStyles.HexNumber)
                    ),

                // #AARRGGBB
                [
                    '#', var a1Char, var a2Char,
                    var r1Char, var r2Char,
                    var g1Char, var g2Char,
                    var b1Char, var b2Char
                ] chars when chars [1..].IsAllAsciiHexDigits () =>
                    new Color (
                        byte.Parse ([r1Char, r2Char], NumberStyles.HexNumber),
                        byte.Parse ([g1Char, g2Char], NumberStyles.HexNumber),
                        byte.Parse ([b1Char, b2Char], NumberStyles.HexNumber),
                        byte.Parse ([a1Char, a2Char], NumberStyles.HexNumber)
                    ),
                _ => throw new ColorParseException (
                        in hexString,
                        $"Color hex string {hexString} was not in a supported format",
                        in hexString
                    )
            },

            // rgb(r,g,b) or rgb(r,g,b,a)
            ['r', 'g', 'b', '(', .., ')'] => ParseRgbaFormat (in text, 4),

            // rgba(r,g,b,a) or rgba(r,g,b)
            ['r', 'g', 'b', 'a', '(', .., ')'] => ParseRgbaFormat (in text, 5),
            // Attempt named colors
            { } when char.IsLetter (text [0]) && ColorStrings.TryParseNamedColor (text, out Color color) => color,
            // Any other input
            _ => throw new ColorParseException (in text, "Text did not match any expected format.", in text, [])
        };

        [Pure]

View on GitHub (pinned to 2e47b11478)

Solutions

1. Verify the string is exactly 4, 5, 7, or 9 chars and that chars[1..] are hex digits before parsing.
2. If you have #RRGGBBAA, reorder alpha to the front (#AARRGGBB) before calling Parse.
3. Use Color.TryParse to gracefully handle malformed hex.

Example fix

// before (wrong: alpha last is unsupported)
Color c = Color.Parse("#FF8800AA");

// after (alpha first, or drop alpha)
Color c = Color.Parse("#AAFF8800");

ReadOnlySpan<char> s = text.AsSpan();
bool ok = s.Length is 4 or 5 or 7 or 9 && s[0]=='#' && s[1..].IsAllAsciiHexDigits();

static bool IsValidHexColor(ReadOnlySpan<char> s) =>
    s.Length is 4 or 5 or 7 or 9 && s[0]=='#' && s[1..].IsAllAsciiHexDigits();

try { c = Color.Parse(hex.AsSpan()); } catch (ColorParseException ex) { /* inspect ex.ColorString */ c = fallback; }

When it happens

Trigger: Passing '#12' (wrong length), '#GGG' or '#12GH56' (non-hex digits), '#12345' (5 chars, no matching pattern), or '#RRGGBBAA' (the library only accepts alpha-first #AARRGGBB, not alpha-last).

Common situations: Confusing #RRGGBBAA (alpha last) with the supported #AARRGGBB (alpha first), copying a CSS hex with trailing alpha in the wrong position, typos, or non-hex characters sneaking into the string.

Related errors

• Value was not composed entirely of decimal digits.
• The text provided consisted of only whitespace characters.
• Text was too short to be any possible supported format.
• Text did not match any expected format.
• Wrong number of values. Expected 3 or 4 decimal integers. Go

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