{"record":{"id":"1003a5700d1a9cac","repo":"roboflow/supervision","slug":"could-not-decode-image-path-image","errorCode":null,"errorMessage":"Could not decode image path ('{image}').","messagePattern":"Could not decode image path \\('(.+?)'\\)\\.","errorType":"exception","errorClass":"OSError","httpStatus":null,"severity":"error","filePath":"src/supervision/draw/utils.py","lineNumber":442,"sourceCode":"        >>> from supervision.draw.utils import draw_image\n        >>> from supervision.geometry.core import Rect\n        >>> scene = np.zeros((100, 100, 3), dtype=np.uint8)\n        >>> image = np.full((40, 40, 3), 255, dtype=np.uint8)\n        >>> rect = Rect(x=10, y=10, width=40, height=40)\n        >>> scene = draw_image(scene, image, opacity=0.8, rect=rect)\n        >>> scene.shape\n        (100, 100, 3)\n\n        ```\n    \"\"\"\n\n    # Validate and load image\n    if isinstance(image, str):\n        if not os.path.exists(image):\n            raise FileNotFoundError(f\"Image path ('{image}') does not exist.\")\n        loaded_image = cv2.imread(image, cv2.IMREAD_UNCHANGED)\n        if loaded_image is None:\n            raise OSError(f\"Could not decode image path ('{image}').\")\n        image_np = cast(npt.NDArray[np.uint8], loaded_image)\n    else:\n        image_np = image\n\n    if image_np.ndim != 3 or image_np.shape[2] not in (3, 4):\n        raise ValueError(\"Image must have 3 or 4 channels.\")\n\n    # Validate opacity\n    if not 0.0 <= opacity <= 1.0:\n        raise ValueError(\"Opacity must be between 0.0 and 1.0.\")\n\n    rect_x = int(rect.x)\n    rect_y = int(rect.y)\n    rect_width = int(rect.width)\n    rect_height = int(rect.height)\n    # Validate rectangle dimensions\n    if (\n        rect_x < 0","sourceCodeStart":424,"sourceCodeEnd":460,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/draw/utils.py#L424-L460","documentation":"OSError raised by draw_image when a path exists but cv2.imread returns None, meaning OpenCV could not decode the file as an image. Existence and decodability are separate: the file may be corrupt, truncated, zero bytes, or an unsupported format. The explicit check distinguishes this from a missing file.","triggerScenarios":"Calling draw_image(scene, path, ...) where path exists but is a text file renamed to .png, a partially downloaded/corrupt image, or a format OpenCV cannot read.","commonSituations":"Interrupted downloads leaving truncated files; SVG or WebP variants OpenCV was not built to decode (no libwebp); empty files created by failed writers; permission issues on some platforms.","solutions":["Verify decodability before use: assert cv2.imread(str(p)) is not None","Re-download or regenerate the corrupt asset; check file size > 0","For exotic formats, convert to PNG with an external tool (Pillow/ImageMagick) first","If OpenCV lacks codec support, install an opencv-python build with the needed codecs"],"exampleFix":"# before\nscene = draw_image(scene, broken_path, opacity=0.8, rect=rect)  # OSError\n\n# after\nimg = cv2.imread(str(logo_path), cv2.IMREAD_UNCHANGED)\nif img is None:\n    raise RuntimeError(f'Undecodable image: {logo_path}')\nscene = draw_image(scene, img, opacity=0.8, rect=rect)","handlingStrategy":"validation","validationCode":"import cv2\n\nimg = cv2.imread(str(logo_path), cv2.IMREAD_UNCHANGED)\nif img is None:\n    raise RuntimeError(f'image not decodable: {logo_path}')\nscene = draw_image(scene, img, opacity=0.8, rect=rect)","typeGuard":"import cv2\nimport numpy as np\n\ndef is_decodable_image(path: str) -> bool:\n    \"\"\"True when OpenCV can decode the file at path.\"\"\"\n    return cv2.imread(path) is not None","tryCatchPattern":"try:\n    scene = draw_image(scene, str(logo_path), opacity=0.8, rect=rect)\nexcept OSError as e:\n    if 'Could not decode' in str(e):\n        raise RuntimeError(f'corrupt image asset: {logo_path}') from e\n    raise","preventionTips":["Pre-decode assets at startup and cache the ndarray, failing fast on corrupt files","Validate downloaded assets: nonzero size and cv2.imread(...) is not None"],"tags":["drawing","image-decode","opencv","file-io"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}