{"record":{"id":"361b159b892bc1a5","repo":"roboflow/supervision","slug":"invalid-hex-color-format-hex-color","errorCode":null,"errorMessage":"Invalid hex color format: {hex_color}","messagePattern":"Invalid hex color format: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/annotators/utils.py","lineNumber":452,"sourceCode":"\n    Raises:\n        ValueError: If the format is invalid.\n\n    Examples:\n        ```pycon\n        >>> from supervision.annotators.utils import hex_to_rgba\n        >>> hex_to_rgba(\"#FF00FF\")\n        (255, 0, 255, 255)\n        >>> hex_to_rgba(\"#FF00FF80\")\n        (255, 0, 255, 128)\n\n        ```\n    \"\"\"\n    hex_color = hex_color.strip().removeprefix(\"#\")\n    if len(hex_color) == 6:\n        hex_color += \"FF\"  # default full opacity\n    if len(hex_color) != 8:\n        raise ValueError(f\"Invalid hex color format: {hex_color}\")\n    try:\n        r = int(hex_color[0:2], 16)\n        g = int(hex_color[2:4], 16)\n        b = int(hex_color[4:6], 16)\n        a = int(hex_color[6:8], 16)\n    except ValueError as exc:\n        raise ValueError(f\"Invalid hex digits in {hex_color}\") from exc\n    return (r, g, b, a)\n\n\ndef rgba_to_hex(rgba: tuple[int, int, int, int]) -> str:\n    \"\"\"\n    Converts an RGBA tuple (0-255 each) to a hex color string.\n\n    Args:\n        rgba: RGBA values in range 0-255.\n\n    Returns:","sourceCodeStart":434,"sourceCodeEnd":470,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/annotators/utils.py#L434-L470","documentation":"Raised by `supervision.annotators.utils.hex_to_rgba` when the input string, after stripping whitespace and removing an optional leading '#', is neither 6 characters (RGB) nor 8 characters (RGBA). The library normalizes 6-digit hex to 8 digits by appending 'FF' (full opacity); any other length is rejected because it cannot be split into RRGGBBAA byte pairs.","triggerScenarios":"Calling `hex_to_rgba(\"#FF0\")` (3-digit shorthand), `hex_to_rgba(\"FF00FF00FF\")` (10 digits), `hex_to_rgba(\"\")`, or `hex_to_rgba(\"#FF00F\")` (5 digits). Also triggered indirectly by passing a malformed hex string to annotator constructors (e.g. `sv.Color.from_hex` or annotators that accept hex strings normalized via `_normalize_color_input`).","commonSituations":"Copying CSS 3-digit shorthand colors (#f00) from a stylesheet into annotator colors; typos or truncated color constants in config files; trailing characters after paste (e.g. '#FF00FF ' survives due to strip, but '#FF00FF0' does not); assuming 4-digit RGBA shorthand (#F00F) is supported like in CSS.","solutions":["Expand the color to 6-digit RGB or 8-digit RGBA form: '#FF00FF' or '#FF00FF80'.","If you have 3-digit CSS shorthand, expand each nibble manually: '#F0A' -> '#FF00AA'.","Validate color strings at startup with `sv.annotators.utils.is_valid_hex` before passing them to annotators."],"exampleFix":"// before\nsv.Color.from_hex(\"#FF0\")  # 3-digit shorthand -> ValueError\n\n// after\nsv.Color.from_hex(\"#FFFF00\")  # 6-digit RGB, alpha defaults to FF","handlingStrategy":"validation","validationCode":"from supervision.annotators.utils import is_valid_hex\n\ndef safe_hex(h: str) -> str:\n    h = h.strip().lstrip('#')\n    if len(h) == 3:  # expand CSS shorthand\n        h = ''.join(c * 2 for c in h)\n    if not is_valid_hex('#' + h):\n        raise ValueError(f\"bad color: {h!r}\")\n    return '#' + h","typeGuard":"def is_valid_hex6_or_8(s: str) -> bool:\n    s = s.strip().lstrip('#')\n    return len(s) in (6, 8) and all(c in '0123456789abcdefABCDEF' for c in s)","tryCatchPattern":null,"preventionTips":["Expand 3-digit CSS shorthand before passing colors to supervision.","Validate all colors from config files with is_valid_hex at startup, not per frame."],"tags":["color","validation","annotators"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}