{"record":{"id":"b57cb7bdfc37d4d3","repo":"roboflow/supervision","slug":"unsupported-image-type-type-image","errorCode":null,"errorMessage":"Unsupported image type: {type(image)}","messagePattern":"Unsupported image type: (.+?)","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/supervision/utils/conversion.py","lineNumber":80,"sourceCode":"    np.ndarray, converts back when processing is complete.\n\n    Assumes the annotators do NOT modify the scene in-place.\n\n    Raises:\n        TypeError: If `image` is not a `numpy.ndarray` or `PIL.Image.Image`.\n    \"\"\"\n\n    @functools.wraps(image_processing_fun)\n    def wrapper(image: ImageType, *args: Any, **kwargs: Any) -> Any:\n        if isinstance(image, np.ndarray):\n            return image_processing_fun(image, *args, **kwargs)\n\n        if isinstance(image, Image.Image):\n            scene = pillow_to_cv2(image)\n            annotated = image_processing_fun(scene, *args, **kwargs)\n            return cv2_to_pillow(annotated)\n\n        raise TypeError(f\"Unsupported image type: {type(image)}\")\n\n    return cast(F, wrapper)\n\n\ndef ensure_pil_image_for_class_method(\n    annotate_func: F,\n) -> F:\n    \"\"\"\n    Decorates image processing functions that accept np.ndarray, converting `image` to\n    PIL image, converts back when processing is complete.\n\n    Assumes the annotators modify the scene in-place.\n\n    Raises:\n        TypeError: If `scene` is not a `numpy.ndarray` or `PIL.Image.Image`.\n    \"\"\"\n\n    @functools.wraps(annotate_func)","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/utils/conversion.py#L62-L98","documentation":"Raised by the ensure_cv2_image_for_function decorator's wrapper in supervision.utils.conversion when the first `image` argument of a decorated standalone image-processing function is neither np.ndarray nor PIL.Image.Image. The decorator converts PIL to BGR array, runs the function, and converts back; unsupported types fail fast with this TypeError.","triggerScenarios":"Calling a decorated module-level function (not a bound method) such as a drawing/utility helper with a torch.Tensor, path string, bytes buffer, or None as the first positional argument.","commonSituations":"Sending raw HTTP image bytes or a base64 string instead of a decoded array; passing a tensor from a deep-learning pipeline; passing a cv2.VideoCapture capture flag or a Path object.","solutions":["Decode bytes to an array first: np.frombuffer(data, np.uint8) then cv2.imdecode(..., cv2.IMREAD_COLOR).","Convert tensors: image = tensor.detach().cpu().numpy().","Load paths with cv2.imread(str(path)) before calling the function.","Verify the argument order — the first positional arg must be the image itself."],"exampleFix":"// before\nresult = draw_helper(image_bytes, detections)  # TypeError\n\n// after\nbuf = np.frombuffer(image_bytes, np.uint8)\nimage = cv2.imdecode(buf, cv2.IMREAD_COLOR)\nresult = draw_helper(image, detections)","handlingStrategy":"type-guard","validationCode":"def to_ndarray_if_needed(image: object) -> np.ndarray | Image.Image:\n    if isinstance(image, (np.ndarray, Image.Image)):\n        return image\n    if hasattr(image, 'detach'):\n        return image.detach().cpu().numpy()\n    raise TypeError(f'Cannot use {type(image)} as an image')","typeGuard":"def is_supported_image(image: object) -> TypeGuard[Union[np.ndarray, Image.Image]]:\n    return isinstance(image, (np.ndarray, Image.Image))","tryCatchPattern":"try:\n    result = decorated_fn(image, ...)\nexcept TypeError as e:\n    if 'Unsupported image type' in str(e):\n        image = np.asarray(decode_anyhow(image))\n        result = decorated_fn(image, ...)\n    else:\n        raise","preventionTips":["Decode network/bytes payloads to np.ndarray at ingest, not at draw time.","Keep tensor-to-NumPy conversion in exactly one helper used everywhere.","Assert the first positional argument type in debug builds."],"tags":["type-error","image-processing","numpy","pillow"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}