tui-cs/Terminal.Gui · error · ColorParseException

Provided text is too short to be any known color format.

Error message

Provided text is too short to be any known color format.

What it means

Thrown by Color.Parse(string?, IFormatProvider?) when the text is non-null/non-whitespace but shorter than 3 characters AND no custom formatProvider is supplied. Terminal.Gui's shortest valid color formats are 3 characters (a ColorName16 alias or '#XY'), so anything shorter cannot be valid; the error is raised eagerly in the string overload before delegating to the span-based parser.

Source

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

    /// <remarks>While <see cref="Color"/> supports the alpha channel <see cref="A"/>, Terminal.Gui does not.</remarks>
    /// <exception cref="ArgumentNullException">If <paramref name="text"/> is <see langword="null"/>.</exception>
    /// <exception cref="ArgumentException">
    ///     If <paramref name="text"/> is an empty string or consists of only whitespace
    ///     characters.
    /// </exception>
    /// <exception cref="ColorParseException">
    ///     If thrown by
    ///     <see cref="Parse(System.ReadOnlySpan{char},System.IFormatProvider?)"/>.
    /// </exception>
    [Pure]
    [SkipLocalsInit]
    public static Color Parse (string? text, IFormatProvider? formatProvider = null)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace (text, nameof (text));

        if (text is { Length: < 3 } && formatProvider is null)
        {
            throw new ColorParseException (
                                           text,
                                           reason: "Provided text is too short to be any known color format.",
                                           badValue: text
                                          );
        }

        return Parse (text.AsSpan (), formatProvider ?? CultureInfo.InvariantCulture);
    }

    /// <summary>
    ///     Converts the provided <see cref="ReadOnlySpan{T}"/> of <see langword="char"/> to a new <see cref="Color"/>
    ///     value.
    /// </summary>
    /// <param name="text">
    ///     The text to analyze. Formats supported are "#RGB", "#RRGGBB", "#RGBA", "#AARRGGBB", "rgb(r,g,b)",
    ///     "rgb(r,g,b,a)", "rgba(r,g,b)", "rgba(r,g,b,a)", and any of the <see cref="ColorName16"/> string values.
    /// </param>
    /// <param name="formatProvider">

View on GitHub (pinned to 2e47b11478)

Solutions

1. Provide a complete color string: '#RRGGBB', '#AARRGGBB', 'rgb(r,g,b)', 'rgba(r,g,b,a)', or a full ColorName16 name.
2. Validate length >= 3 (and ideally matches a known format) before calling Parse, or use Color.TryParse if available.
3. Pass an ICustomColorFormatter as formatProvider if you have a shorter custom encoding you want to decode yourself.

Example fix

// before
Color c = Color.Parse (userInput); // throws if userInput is "#"

// after
if (userInput.Length < 3)
    return Color.Default;
Color c = Color.Parse (userInput);

if (string.IsNullOrWhiteSpace (text) || text.Length < 3)
    return Color.Default;
Color c = Color.Parse (text);

static bool IsPlausibleColorString (string s) => !string.IsNullOrWhiteSpace (s) && s.Length >= 3;

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

When it happens

Trigger: Calling Color.Parse("a"), Color.Parse("#"), Color.Parse(""), or any 1-2 character input without an ICustomColorFormatter. Note ArgumentException.ThrowIfNullOrWhiteSpace already handles null/whitespace earlier, so this fires for short non-whitespace strings.

Common situations: Reading color values from a config/UI field without length validation; a truncated hex string; a user typing a partial color name.

Related errors

• The text provided was null or empty.
• 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/3e43896e45a95f5a. Report an issue: GitHub.