tui-cs/Terminal.Gui · error · ArgumentOutOfRangeException

Fraction must be between 0 and 1.

Error message

Fraction must be between 0 and 1.

What it means

Thrown by Gradient.GetColorAtFraction when the fraction is outside [0,1]. Note that NaN is explicitly handled (returns the last spectrum color) and does NOT throw; only values below 0 or above 1 do. It is an ArgumentOutOfRangeException. The fraction maps a position along the generated spectrum.

Source

Thrown at Terminal.Gui/Drawing/Gradient.cs:110

    ///     Returns the color to use at the given part of the spectrum
    /// </summary>
    /// <param name="fraction">
    ///     Proportion of the way through the spectrum, must be between
    ///     0 and 1 (inclusive).  Returns the last color if <paramref name="fraction"/> is
    ///     <see cref="double.NaN"/>.
    /// </param>
    /// <returns></returns>
    /// <exception cref="ArgumentOutOfRangeException"></exception>
    public Color GetColorAtFraction (double fraction)
    {
        if (double.IsNaN (fraction))
        {
            return Spectrum.Last ();
        }

        if (fraction is < 0 or > 1)
        {
            throw new ArgumentOutOfRangeException (nameof (fraction), @"Fraction must be between 0 and 1.");
        }

        var index = (int)(fraction * (Spectrum.Count - 1));

        return Spectrum [index];
    }

    private List<Color> GenerateGradient (IEnumerable<int> steps)
    {
        List<Color> gradient = new ();

        if (_stops.Count == 1)
        {
            for (var i = 0; i < steps.Sum (); i++)
            {
                gradient.Add (_stops [0]);
            }

View on GitHub (pinned to 2e47b11478)

Solutions

1. Clamp the fraction: double f = Math.Clamp(value, 0.0, 1.0); before calling.
2. Normalize the source value by its full range before calling.
3. Handle NaN explicitly if your source can produce it (it won't throw, but clamp for determinism).

Example fix

// before
Color c = gradient.GetColorAtFraction(progress / max);

// after
double f = Math.Clamp(progress / (double)max, 0.0, 1.0);
Color c = gradient.GetColorAtFraction(f);

double f = double.IsNaN(fraction) ? 1.0 : Math.Clamp(fraction, 0.0, 1.0);

static bool IsValidFraction(double f) => double.IsNaN(f) || f is >= 0.0 and <= 1.0;

try { c = gradient.GetColorAtFraction(f); } catch (ArgumentOutOfRangeException) { c = gradient.GetColorAtFraction(0); }

When it happens

Trigger: Calling gradient.GetColorAtFraction(1.5), GetColorAtFraction(-0.1), or passing an un-normalized ratio like progress/50 where progress can exceed the denominator.

Common situations: Passing a raw progress value instead of a normalized fraction, animation/easing producing overshoot above 1, or division producing negative results.

Related errors

• At least one color stop must be provided.
• Steps must be greater than 0.
• Number of steps must be N-1
• Provided text is too short to be any known color format.
• The text provided was null or empty.

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