spectreconsole/spectre.console · error · InvalidOperationException

Cannot convert color to console color.

Error message

Cannot convert color to console color.

What it means

A switch expression maps the 16 standard ANSI colors (indices 0-15) to System.ConsoleColor values; the default arm '_' throws InvalidOperationException for any color number outside 0-15 (i.e. the 256-color palette entries 16-255, which have no ConsoleColor equivalent).

Source

Thrown at src/Spectre.Console.Ansi/Color.cs:207

        return color.Number.Value switch
        {
            0 => ConsoleColor.Black,
            1 => ConsoleColor.DarkRed,
            2 => ConsoleColor.DarkGreen,
            3 => ConsoleColor.DarkYellow,
            4 => ConsoleColor.DarkBlue,
            5 => ConsoleColor.DarkMagenta,
            6 => ConsoleColor.DarkCyan,
            7 => ConsoleColor.Gray,
            8 => ConsoleColor.DarkGray,
            9 => ConsoleColor.Red,
            10 => ConsoleColor.Green,
            11 => ConsoleColor.Yellow,
            12 => ConsoleColor.Blue,
            13 => ConsoleColor.Magenta,
            14 => ConsoleColor.Cyan,
            15 => ConsoleColor.White,
            _ => throw new InvalidOperationException("Cannot convert color to console color."),
        };
    }

    /// <summary>
    /// Converts a color number into a <see cref="Color"/>.
    /// </summary>
    /// <param name="number">The color number.</param>
    /// <returns>The color representing the specified color number.</returns>
    public static Color FromInt32(int number)
    {
        return ColorTable.GetColor(number);
    }

    /// <summary>
    /// Creates a color from a hexadecimal string representation.
    /// </summary>
    /// <param name="hex">The hexadecimal string representation of the color.</param>
    /// <returns>The color created from the hexadecimal string.</returns>

View on GitHub (pinned to 0acc92fada)

Solutions

1. Restrict colors to the 0-15 range when a ConsoleColor is required
2. Guard the conversion: check the color number is <= 15 before calling, and pick a fallback ConsoleColor otherwise
3. Avoid mixing true-color Spectre output with System.ConsoleColor-based APIs

Example fix

// before
var cc = color.ToConsoleColor(); // throws if color.Number > 15

// after
var cc = color.Number <= 15
    ? color.ToConsoleColor()
    : ConsoleColor.Gray; // safe fallback

// Guard the conversion against out-of-range palette indices:
ConsoleColor cc = color.Number is >= 0 and <= 15
    ? color.ToConsoleColor()
    : ConsoleColor.Gray; // or another safe fallback

public static bool HasConsoleColorEquivalent(Color c) => c.Number is >= 0 and <= 15;

ConsoleColor cc;
try { cc = color.ToConsoleColor(); }
catch (InvalidOperationException ex) when (ex.Message == "Cannot convert color to console color.")
{ cc = ConsoleColor.Gray; }

When it happens

Trigger: Calling this ConsoleColor conversion on a Color whose number is >= 16 (e.g. a true-color/RGB-derived color or a high palette index), when the runtime/console only supports the 16-color mapping.

Common situations: Constructing a Color via rgb()/hex that resolves to a palette index beyond 15 and then asking for its ConsoleColor; downgrading a rich-color Spectre pipeline to a legacy ConsoleColor API; running on a terminal that requested 256-color output.

Related errors

• Color number must be greater than or equal to 0 (was {number
• Color number must be less than or equal to 255 (was {number}
• Could not find color '{part}'.
• Could not find color or style '{part}'.
• A foreground color has already been set.

AI-assisted analysis of spectreconsole/spectre.console@0acc92fada (2026-08-13). Data as JSON: /api/errors/faa537be0e0709a6. Report an issue: GitHub.