roboflow/supervision · error · ValueError

Could not read image from path: {image_path}

Error message

Could not read image from path: {image_path}

What it means

Raised during Pascal VOC dataset loading when cv2.imread returns None for an image path listed in the images directory. OpenCV returns None (instead of raising) for missing files, unreadable/corrupt images, or formats it cannot decode, so supervision converts that into an explicit ValueError naming the path. The image is read to derive resolution_wh for mask construction.

Source

Thrown at src/supervision/dataset/formats/pascal_voc.py:244

        image_paths,
        total=len(image_paths),
        desc="Loading Pascal VOC annotations",
        disable=not show_progress,
    ):
        image_stem = Path(image_path).stem
        annotation_path = os.path.join(annotations_directory_path, f"{image_stem}.xml")
        if not os.path.exists(annotation_path):
            annotations[image_path] = Detections.empty()
            continue

        tree = parse(annotation_path)
        root = tree.getroot()
        if root is None:
            raise ValueError(f"Failed to parse XML root from {annotation_path}")

        image = cv2.imread(image_path)
        if image is None:
            raise ValueError(f"Could not read image from path: {image_path}")
        resolution_wh = (image.shape[1], image.shape[0])
        annotation, classes = detections_from_xml_obj(
            root, classes, resolution_wh, force_masks
        )
        annotations[image_path] = annotation

    return classes, image_paths, annotations


def detections_from_xml_obj(
    root: Element,
    classes: list[str],
    resolution_wh: tuple[int, int],
    force_masks: bool = False,
) -> tuple[Detections, list[str]]:
    """
    Converts an XML object in Pascal VOC format to a Detections object.
    Expected XML format:

View on GitHub (pinned to 7f254d9784)

Solutions

1. Open the exact path from the error in an image viewer / `file <path>` to confirm it is a readable image.
2. If the file is corrupt or truncated, delete or re-download it (and its .xml if needed).
3. Verify the images_directory_path you passed actually contains the images (path typo / wrong split folder).
4. For non-ASCII path issues on Windows, either rename files to ASCII or pass a short ASCII path (e.g. copy to a temp dir) before loading.
5. Confirm cv2 has the codec: python -c "import cv2; print(cv2.imread('that_file.jpg') is not None)".

Example fix

# before
dataset = sv.DetectionDataset.from_pascal_voc(
    images_directory_path='dataset/images', ...)

# after: pre-validate and skip unreadable images
from pathlib import Path
import cv2
bad = [p for p in Path('dataset/images').glob('*')
       if cv2.imread(str(p)) is None]
print('unreadable:', bad)

from pathlib import Path
import cv2

def unreadable_images(directory: str) -> list[Path]:
    """Return image files cv2 cannot read before dataset loading."""
    return [p for p in Path(directory).iterdir()
            if not p.is_dir() and cv2.imread(str(p)) is None]

try:
    dataset = sv.DetectionDataset.from_pascal_voc(images_dir, ann_dir)
except ValueError as e:
    if 'Could not read image' in str(e):
        bad = str(e).split('path: ')[-1].strip()
        # move both image and its xml aside, then retry once
        Path(bad).rename(bad + '.bad')
        Path(ann_dir, Path(bad).stem + '.xml').rename(
            str(Path(ann_dir, Path(bad).stem + '.xml')) + '.bad')
        dataset = sv.DetectionDataset.from_pascal_voc(images_dir, ann_dir)
    else:
        raise

When it happens

Trigger: DetectionDataset.from_pascal_voc(...) where an image path contains a corrupt/truncated file, an unsupported extension that survived the directory glob, a permissions problem, or a path with characters cv2.imread cannot open (e.g. non-ASCII paths on some Windows builds).

Common situations: Truncated downloads, images with a .jpg extension but non-image content, mismatched directory layout between images and annotations, files still being written by another process, or OpenCV built without the needed codec (e.g. no JPEG support).

Related errors

• Could not read image from path: {image_path}
• Failed to parse XML root from {annotation_path}
• Missing bndbox in Pascal VOC annotation.
• Missing polygon coordinate value in Pascal VOC.
• All sigma values must be positive

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