tui-cs/Terminal.Gui · error · ColorParseException

The text provided was null or empty.

Error message

The text provided was null or empty.

What it means

Thrown by Color.Parse(ReadOnlySpan<char>, IFormatProvider?) when the input span is empty (IsEmpty) and no custom formatProvider is supplied. This is the span-overload equivalent of 'you handed me nothing to parse'. An empty span cannot match any color format, so a ColorParseException is raised with the empty span as the bad value.

Source

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

    ///     <br/> Defaults to <see cref="CultureInfo.InvariantCulture"/> if <see langword="null"/>. <br/> If not null, must
    ///     implement <see cref="ICustomColorFormatter"/> or will be ignored and <see cref="CultureInfo.InvariantCulture"/>
    ///     will be used.
    /// </param>
    /// <returns>A <see cref="Color"/> value equivalent to <paramref name="text"/>, if parsing was successful.</returns>
    /// <remarks>While <see cref="Color"/> supports the alpha channel <see cref="A"/>, Terminal.Gui does not.</remarks>
    /// <exception cref="ArgumentException">
    ///     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 () =>

View on GitHub (pinned to 2e47b11478)

Solutions

1. Check text.IsEmpty before calling Parse and return a default/skip the parse.
2. Pass an ICustomColorFormatter as formatProvider — the {IsEmpty:false} when ICustomColorFormatter arm handles empty input by delegating to the formatter (though note it requires non-empty too; ensure your formatter handles empty).
3. Route user input through the string overload which gives the more specific 'too short' message for non-empty short strings.

Example fix

// before
Color c = Color.Parse (someSpan); // throws if someSpan.IsEmpty

// after
if (someSpan.IsEmpty) return Color.Default;
Color c = Color.Parse (someSpan);

if (text.IsEmpty) return Color.Default;
Color c = Color.Parse (text);

static bool IsNonEmptySpan (ReadOnlySpan<char> s) => !s.IsEmpty;

try { return Color.Parse (text); }
catch (ColorParseException) { return Color.Default; }

When it happens

Trigger: Calling Color.Parse(ReadOnlySpan<char>.Empty), Color.Parse("".AsSpan()), or passing a span that was sliced to zero length. Distinguished from error 98 because this is the span overload and triggers on empty (Length 0), not merely short.

Common situations: Slicing a span past its end; reading an empty field from a parsed token; passing default(ReadOnlySpan<char>) by mistake.

Related errors

• Provided text is too short to be any known color format.
• The text provided consisted of only whitespace characters.
• Text was too short to be any possible supported format.
• Wrong number of values. Expected 3 or 4 decimal integers. Go
• Unable to create string from Color with value {Argb}, using

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