Textualize/rich · error · ColorParseError

color number must be <= 255 in {color!r}

Error message

color number must be <= 255 in {color!r}

What it means

When a color string parses as a bare integer (the color_8 branch of RE_COLOR, e.g. "214"), rich checks the ANSI palette range and raises ColorParseError if the number exceeds 255. ANSI 8-bit color indices only run 0-255 (0-15 standard, 16-255 as the 6x6x6 cube + grayscale), so anything larger has no terminal representation.

Source

Thrown at rich/color.py:463

                type=(ColorType.STANDARD if color_number < 16 else ColorType.EIGHT_BIT),
                number=color_number,
            )

        color_match = RE_COLOR.match(color)
        if color_match is None:
            raise ColorParseError(f"{original_color!r} is not a valid color")

        color_24, color_8, color_rgb = color_match.groups()
        if color_24:
            triplet = ColorTriplet(
                int(color_24[0:2], 16), int(color_24[2:4], 16), int(color_24[4:6], 16)
            )
            return cls(color, ColorType.TRUECOLOR, triplet=triplet)

        elif color_8:
            number = int(color_8)
            if number > 255:
                raise ColorParseError(f"color number must be <= 255 in {color!r}")
            return cls(
                color,
                type=(ColorType.STANDARD if number < 16 else ColorType.EIGHT_BIT),
                number=number,
            )

        else:  #  color_rgb:
            components = color_rgb.split(",")
            if len(components) != 3:
                raise ColorParseError(
                    f"expected three components in {original_color!r}"
                )
            red, green, blue = components
            triplet = ColorTriplet(int(red), int(green), int(blue))
            if not all(component <= 255 for component in triplet):
                raise ColorParseError(
                    f"color components must be <= 255 in {original_color!r}"
                )

View on GitHub (pinned to 9d8f9a372c)

Solutions

1. Clamp or modulo the computed index into 0-255 before passing it (e.g. min(255, max(0, idx)))
2. Fix the value in the config/style string to an integer in 0-255
3. If you meant a specific RGB color, use the "rgb(r,g,b)" or "#rrggbb" form instead of a bare index

Example fix

// before (Python)
Color.parse(str(16 + 36*7))   # 268 -> ColorParseError
// after
idx = 16 + 36*6 + 5           # max valid cube index
Color.parse(str(min(idx, 255)))

if not (isinstance(n, int) and 0 <= n <= 255):
    n = max(0, min(255, int(n)))
color = Color.parse(str(n))

def is_valid_ansi_index(v: int) -> bool:
    return isinstance(v, int) and 0 <= v <= 255

from rich.color import ColorParseError

try:
    color = Color.parse(str(idx))
except ColorParseError:
    idx &= 0xFF  # or clamp
    color = Color.parse(str(idx))

When it happens

Trigger: Color.parse("256"), Color.parse("300"), or style strings like "color 999"; computing a color index arithmetically (e.g. 16 + 36*r + 6*g + b) and passing an out-of-range result; passing a channel value like 255 as a component but a stray composite >255 as an index.

Common situations: Off-by-one math when mapping data values onto the 256-color cube; using RGB channel values (0-255 each) directly as palette indices; config files storing "color: 300".

Related errors

• color components must be <= 255 in {original_color!r}
• {original_color!r} is not a valid color
• expected three components in {original_color!r}
• invalid value for align, expected "left", "center", or "righ
• invalid value for vertical, expected "top", "middle", or "bo

AI-assisted analysis of Textualize/rich@9d8f9a372c (2026-08-15). Data as JSON: /api/errors/1e35e1ed61c4ac20. Report an issue: GitHub.