roboflow/supervision · error · ValueError

Invalid hex digits in {hex_color}

Error message

Invalid hex digits in {hex_color}

What it means

Raised by `hex_to_rgba` when the string has the correct length (6 or 8 after '#' removal) but contains characters that are not valid hexadecimal digits. The length check passes first, then `int(slice, 16)` fails and the error is re-raised with a clearer message.

Source

Thrown at src/supervision/annotators/utils.py:459

        >>> hex_to_rgba("#FF00FF")
        (255, 0, 255, 255)
        >>> hex_to_rgba("#FF00FF80")
        (255, 0, 255, 128)

        ```
    """
    hex_color = hex_color.strip().removeprefix("#")
    if len(hex_color) == 6:
        hex_color += "FF"  # default full opacity
    if len(hex_color) != 8:
        raise ValueError(f"Invalid hex color format: {hex_color}")
    try:
        r = int(hex_color[0:2], 16)
        g = int(hex_color[2:4], 16)
        b = int(hex_color[4:6], 16)
        a = int(hex_color[6:8], 16)
    except ValueError as exc:
        raise ValueError(f"Invalid hex digits in {hex_color}") from exc
    return (r, g, b, a)


def rgba_to_hex(rgba: tuple[int, int, int, int]) -> str:
    """
    Converts an RGBA tuple (0-255 each) to a hex color string.

    Args:
        rgba: RGBA values in range 0-255.

    Returns:
        Hex color string in the format "#RRGGBBAA".

    Raises:
        ValueError: If `rgba` is not a 4-tuple or contains values outside 0-255.

    Examples:
        ```pycon

View on GitHub (pinned to 7f254d9784)

Solutions

1. Fix the offending character — every character must be 0-9, a-f, or A-F.
2. Validate user-supplied colors at load time with `is_valid_hex` from `supervision.annotators.utils` and reject early with a clear config error.
3. If colors come from an untrusted source, normalize/scrub non-ASCII characters before parsing.

Example fix

# before
sv.Color.from_hex("#FF00FF8O")  # letter O -> ValueError: Invalid hex digits

# after
sv.Color.from_hex("#FF00FF80")  # zero

from supervision.annotators.utils import is_valid_hex

for name, color in config['colors'].items():
    if not is_valid_hex(color):
        raise ConfigError(f"invalid hex color for {name}: {color!r}")

import re
HEX_RE = re.compile(r'^#?[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$')

def is_hex_color(s: str) -> bool:
    return isinstance(s, str) and HEX_RE.match(s) is not None

When it happens

Trigger: Calling `hex_to_rgba("#GG00FF")` (G is not hex), `hex_to_rgba("FF00FF8O")` (letter O instead of zero), or strings containing whitespace in the middle or punctuation like '#FF,0FF'. Mixed-case valid hex ('#ff00ff') does NOT trigger this — only non-hex characters do.

Common situations: OCR or hand-transcribed color values with O/0 or l/1 confusion; color strings loaded from CSV/JSON config containing typos; locale-related full-width characters pasted from rich-text editors; colors copied from design tools that emit shorthand like '#FFF' hit error 280 instead, while character typos hit this one.

Related errors

• Invalid hex color format: {hex_color}
• RGBA must be a 4-tuple with values between 0-255.
• module {__name__} has no attribute {name}
• Edge indices must use the 1-based convention and be within t
• sigma must contain at least one value

AI-assisted analysis of roboflow/supervision@7f254d9784 (2026-08-15). Data as JSON: /api/errors/1aacd3c88fda935c. Report an issue: GitHub.