roboflow/supervision · error · OSError

Could not decode image path ('{image}').

Error message

Could not decode image path ('{image}').

What it means

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.

Source

Thrown at src/supervision/draw/utils.py:442

        >>> from supervision.draw.utils import draw_image
        >>> from supervision.geometry.core import Rect
        >>> scene = np.zeros((100, 100, 3), dtype=np.uint8)
        >>> image = np.full((40, 40, 3), 255, dtype=np.uint8)
        >>> rect = Rect(x=10, y=10, width=40, height=40)
        >>> scene = draw_image(scene, image, opacity=0.8, rect=rect)
        >>> scene.shape
        (100, 100, 3)

        ```
    """

    # Validate and load image
    if isinstance(image, str):
        if not os.path.exists(image):
            raise FileNotFoundError(f"Image path ('{image}') does not exist.")
        loaded_image = cv2.imread(image, cv2.IMREAD_UNCHANGED)
        if loaded_image is None:
            raise OSError(f"Could not decode image path ('{image}').")
        image_np = cast(npt.NDArray[np.uint8], loaded_image)
    else:
        image_np = image

    if image_np.ndim != 3 or image_np.shape[2] not in (3, 4):
        raise ValueError("Image must have 3 or 4 channels.")

    # Validate opacity
    if not 0.0 <= opacity <= 1.0:
        raise ValueError("Opacity must be between 0.0 and 1.0.")

    rect_x = int(rect.x)
    rect_y = int(rect.y)
    rect_width = int(rect.width)
    rect_height = int(rect.height)
    # Validate rectangle dimensions
    if (
        rect_x < 0

View on GitHub (pinned to 7f254d9784)

Solutions

1. Verify decodability before use: assert cv2.imread(str(p)) is not None
2. Re-download or regenerate the corrupt asset; check file size > 0
3. For exotic formats, convert to PNG with an external tool (Pillow/ImageMagick) first
4. If OpenCV lacks codec support, install an opencv-python build with the needed codecs

Example fix

# before
scene = draw_image(scene, broken_path, opacity=0.8, rect=rect)  # OSError

# after
img = cv2.imread(str(logo_path), cv2.IMREAD_UNCHANGED)
if img is None:
    raise RuntimeError(f'Undecodable image: {logo_path}')
scene = draw_image(scene, img, opacity=0.8, rect=rect)

import cv2

img = cv2.imread(str(logo_path), cv2.IMREAD_UNCHANGED)
if img is None:
    raise RuntimeError(f'image not decodable: {logo_path}')
scene = draw_image(scene, img, opacity=0.8, rect=rect)

import cv2
import numpy as np

def is_decodable_image(path: str) -> bool:
    """True when OpenCV can decode the file at path."""
    return cv2.imread(path) is not None

try:
    scene = draw_image(scene, str(logo_path), opacity=0.8, rect=rect)
except OSError as e:
    if 'Could not decode' in str(e):
        raise RuntimeError(f'corrupt image asset: {logo_path}') from e
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Could not open video at {source_path}
• Could not open video at {video_path}
• Could not open video writer for {self.target_path}
• Image must have 3 or 4 channels.
• Image path ('{image}') does not exist.

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