roboflow/supervision · error · FileNotFoundError

Image path ('{image}') does not exist.

Error message

Image path ('{image}') does not exist.

What it means

FileNotFoundError raised by draw_image when the image argument is a path string that does not exist on disk (checked with os.path.exists before any decode attempt). The API accepts either an in-memory array or a path; for paths it validates existence up front so you get a clear message instead of a decode failure.

Source

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

    Example:
        ```pycon
        >>> import numpy as np
        >>> 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)

View on GitHub (pinned to 7f254d9784)

Solutions

1. Use an absolute path: Path(__file__).parent / 'assets' / 'logo.png'
2. Verify existence in your loader: if not p.is_file(): raise with a clear message
3. Load the image yourself (cv2.imread) and pass the ndarray, keeping file handling in your code

Example fix

# before
scene = draw_image(scene, 'assets/logo.png', opacity=0.8, rect=rect)  # CWD-dependent

# after
from pathlib import Path
logo_path = Path(__file__).parent / 'assets' / 'logo.png'
scene = draw_image(scene, str(logo_path), opacity=0.8, rect=rect)

from pathlib import Path

logo_path = Path(logo_path)
if not logo_path.is_file():
    raise FileNotFoundError(f'logo asset missing: {logo_path}')
scene = draw_image(scene, str(logo_path), opacity=0.8, rect=rect)

from pathlib import Path

def is_readable_file(path: object) -> bool:
    """True when path is an existing file Path/str."""
    return isinstance(path, (str, Path)) and Path(path).is_file()

try:
    scene = draw_image(scene, str(logo_path), opacity=0.8, rect=rect)
except FileNotFoundError as e:
    # fall back to a bundled asset or skip drawing
    if (fallback := Path(__file__).parent / 'assets' / 'logo.png').is_file():
        scene = draw_image(scene, str(fallback), opacity=0.8, rect=rect)
    else:
        raise

When it happens

Trigger: Calling draw_image(scene, 'assets/logo.png', ...) where the relative path is wrong for the current working directory, or the file was never created/moved.

Common situations: Relative paths resolved against a different CWD (script run from another directory); asset paths in notebooks vs packaged apps; missing assets in Docker images or frozen executables.

Related errors

• Could not open video at {source_path}
• Could not open video at {video_path}
• Could not decode image path ('{image}').
• Could not read image from path: {image_path}
• Could not open video writer for {self.target_path}

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