roboflow/supervision · error · ValueError

Unsupported color conversion code: {code}

Error message

Unsupported color conversion code: {code}

What it means

The fallback `cv2.cvtColor` at src/supervision/_cv2/_color.py:57 implements exactly the conversions supervision itself needs: BGR<->RGB, GRAY2BGR, BGR2GRAY, and HSV2BGR. Any other conversion code constant (e.g. COLOR_BGR2HSV, COLOR_BGR2Lab, COLOR_YUV2BGR) raises with the offending code in the message.

Source

Thrown at src/supervision/_cv2/_color.py:57

                values[..., 0] * 3735
                + values[..., 1] * 19235
                + values[..., 2] * 9798
                + (1 << 14)
            ) >> 15
            return weighted.astype(np.uint8)
        float_values = (
            image[..., 0].astype(np.float64) * 0.114
            + image[..., 1].astype(np.float64) * 0.587
            + image[..., 2].astype(np.float64) * 0.299
        )
        return _cast_array_like_opencv(float_values, image.dtype)

    if code == _COLOR_HSV2BGR:
        if image.ndim != 3 or image.shape[2] != 3:
            raise ValueError("HSV2BGR conversion requires a three-channel image")
        return _hsv_to_bgr(image)

    raise ValueError(f"Unsupported color conversion code: {code}")


def _hsv_to_bgr(image: npt.NDArray[Any]) -> npt.NDArray[Any]:
    """Convert OpenCV's 8-bit HSV representation to BGR."""
    values = image.astype(np.float64)
    hue = values[..., 0] / 30.0
    saturation = values[..., 1] / 255.0
    value = values[..., 2] / 255.0

    chroma = value * saturation
    sector_index = np.floor(hue).astype(np.int64) % 6
    sector = hue - np.floor(hue)
    x = chroma * (1 - np.abs(((sector_index + sector) % 2) - 1))
    match = value - chroma
    zeros = np.zeros_like(chroma)

    red = np.choose(sector_index, (chroma, x, zeros, zeros, x, chroma))
    green = np.choose(sector_index, (x, chroma, chroma, x, zeros, zeros))

View on GitHub (pinned to 7f254d9784)

Solutions

  1. Restrict conversions to the supported set (BGR2RGB/RGB2BGR, GRAY2BGR, BGR2GRAY, HSV2BGR)
  2. Install `opencv-python` — the full conversion matrix comes back
  3. Gate unsupported conversions behind a `BACKEND_NAME == 'opencv'` check and skip/ substitute features on the fallback

Example fix

// before
hsv = cv2.cvtColor(frame, cv2.COLOR_BGR2HSV)

// after (no cv2 available)
gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)  # supported by the fallback
# or: pip install opencv-python to unlock COLOR_BGR2HSV
Defensive patterns

Strategy: fallback

Validate before calling

from supervision._cv2 import BACKEND_NAME

SUPPORTED_CODES = {"COLOR_BGR2RGB", "COLOR_RGB2BGR", "COLOR_GRAY2BGR", "COLOR_BGR2GRAY", "COLOR_HSV2BGR"}

def assert_conversion_supported(code_name: str) -> None:
    """Fail fast when a cvtColor code is unavailable on the fallback backend."""
    if BACKEND_NAME != "opencv" and code_name not in SUPPORTED_CODES:
        raise ValueError(f"cvtColor code {code_name} needs opencv-python installed")

Prevention

When it happens

Trigger: Calling `cv2.cvtColor(img, cv2.COLOR_BGR2HSV)` or any unsupported code while opencv-python is absent and the NumPy fallback backend is active.

Common situations: Application code that assumes real cv2 is present using color spaces beyond the supported set (HSV conversion for classic segmentation, Lab for color distance) in slim Docker/serverless environments.

Related errors

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