tui-cs/Terminal.Gui · error · ColorParseException

The text provided consisted of only whitespace characters.

Error message

The text provided consisted of only whitespace characters.

What it means

Thrown by Color.Parse(ReadOnlySpan<char>) when the input is non-empty but consists entirely of whitespace characters (spaces, tabs, etc.). It surfaces as a ColorParseException, which derives from FormatException. No supported color format (#RGB, rgb(...), named colors) can be whitespace-only, so the parser rejects it outright before attempting any format match. The string overload guards earlier via ArgumentException.ThrowIfNullOrWhiteSpace, so this path is mainly hit through the span-based Parse/TryParse entry points.

Source

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

    ///     with an inner <see cref="FormatException"/> if <paramref name="text"/> was unable
    ///     to be successfully parsed as a <see cref="Color"/>, for any reason.
    /// </exception>
    [Pure]
    [SkipLocalsInit]
    public static Color Parse (ReadOnlySpan<char> text, IFormatProvider? formatProvider = null)
    {
        return text switch
        {
            // Null string or empty span provided
            { IsEmpty: true } when formatProvider is null =>
                throw new ColorParseException (in text, "The text provided was null or empty.", in text),

            // A valid ICustomColorFormatter was specified and the text wasn't null or empty
            { IsEmpty: false } when formatProvider is ICustomColorFormatter f => f.Parse (text),

            // Input string is only whitespace
            { Length: > 0 } when text.IsWhiteSpace () =>
                throw new ColorParseException (in text, "The text provided consisted of only whitespace characters.", in text),

            // Any string too short to possibly be any supported format.
            { Length: > 0 and < 3 } =>
                throw new ColorParseException (in text, "Text was too short to be any possible supported format.", in text),

            // The various hexadecimal cases
            ['#', ..] hexString => hexString switch
            {
                // #RGB
                ['#', var rChar, var gChar, var bChar] chars when chars [1..]
                    .IsAllAsciiHexDigits () =>
                        new Color (
                            byte.Parse ([rChar, rChar], NumberStyles.HexNumber),
                            byte.Parse ([gChar, gChar], NumberStyles.HexNumber),
                            byte.Parse ([bChar, bChar], NumberStyles.HexNumber)
                        ),

                // #ARGB

View on GitHub (pinned to 2e47b11478)

Solutions

1. Trim the input and reject empty/whitespace before parsing: if (string.IsNullOrWhiteSpace(s)) return fallback;
2. Prefer Color.TryParse(...) which returns false instead of throwing for any parse failure.
3. Validate explicitly: if (text.AsSpan().IsWhiteSpace()) handle invalid input.

Example fix

// before
Color c = Color.Parse(userInput.AsSpan());

// after
if (!Color.TryParse(userInput.AsSpan(), null, out Color c))
{
    c = Color.White; // safe default
}

if (text.AsSpan().IsEmpty || text.AsSpan().IsWhiteSpace()) return fallbackColor;

static bool IsParsableColorText(ReadOnlySpan<char> s) => !s.IsEmpty && !s.IsWhiteSpace() && s.Length >= 3;

try { c = Color.Parse(s.AsSpan()); } catch (ColorParseException) { c = fallback; } // prefer Color.TryParse instead

When it happens

Trigger: Calling Color.Parse(" ".AsSpan()) or Color.TryParse(" \t ".AsSpan(), null, out _) with a span that is non-empty yet only whitespace. Also reached when an ICustomColorFormatter is not supplied and the span is whitespace.

Common situations: Theme/configuration JSON values that contain stray spaces instead of a color, user input that was trimmed down to spaces, or copied color strings with leading/trailing whitespace that replaced the real value.

Related errors

• Text was too short to be any possible supported format.
• Wrong number of values. Expected 3 or 4 decimal integers. Go
• Provided text is too short to be any known color format.
• The text provided was null or empty.
• Color hex string {hexString} was not in a supported format

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