{"record":{"id":"5c0502dcfcde20ac","repo":"roboflow/supervision","slug":"could-not-read-image-from-path-image-path-5c0502","errorCode":null,"errorMessage":"Could not read image from path: {image_path}","messagePattern":"Could not read image from path: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/dataset/formats/pascal_voc.py","lineNumber":244,"sourceCode":"        image_paths,\n        total=len(image_paths),\n        desc=\"Loading Pascal VOC annotations\",\n        disable=not show_progress,\n    ):\n        image_stem = Path(image_path).stem\n        annotation_path = os.path.join(annotations_directory_path, f\"{image_stem}.xml\")\n        if not os.path.exists(annotation_path):\n            annotations[image_path] = Detections.empty()\n            continue\n\n        tree = parse(annotation_path)\n        root = tree.getroot()\n        if root is None:\n            raise ValueError(f\"Failed to parse XML root from {annotation_path}\")\n\n        image = cv2.imread(image_path)\n        if image is None:\n            raise ValueError(f\"Could not read image from path: {image_path}\")\n        resolution_wh = (image.shape[1], image.shape[0])\n        annotation, classes = detections_from_xml_obj(\n            root, classes, resolution_wh, force_masks\n        )\n        annotations[image_path] = annotation\n\n    return classes, image_paths, annotations\n\n\ndef detections_from_xml_obj(\n    root: Element,\n    classes: list[str],\n    resolution_wh: tuple[int, int],\n    force_masks: bool = False,\n) -> tuple[Detections, list[str]]:\n    \"\"\"\n    Converts an XML object in Pascal VOC format to a Detections object.\n    Expected XML format:","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/dataset/formats/pascal_voc.py#L226-L262","documentation":"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.","triggerScenarios":"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).","commonSituations":"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).","solutions":["Open the exact path from the error in an image viewer / `file <path>` to confirm it is a readable image.","If the file is corrupt or truncated, delete or re-download it (and its .xml if needed).","Verify the images_directory_path you passed actually contains the images (path typo / wrong split folder).","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.","Confirm cv2 has the codec: python -c \"import cv2; print(cv2.imread('that_file.jpg') is not None)\"."],"exampleFix":"# before\ndataset = sv.DetectionDataset.from_pascal_voc(\n    images_directory_path='dataset/images', ...)\n\n# after: pre-validate and skip unreadable images\nfrom pathlib import Path\nimport cv2\nbad = [p for p in Path('dataset/images').glob('*')\n       if cv2.imread(str(p)) is None]\nprint('unreadable:', bad)","handlingStrategy":"validation","validationCode":"from pathlib import Path\nimport cv2\n\ndef unreadable_images(directory: str) -> list[Path]:\n    \"\"\"Return image files cv2 cannot read before dataset loading.\"\"\"\n    return [p for p in Path(directory).iterdir()\n            if not p.is_dir() and cv2.imread(str(p)) is None]","typeGuard":null,"tryCatchPattern":"try:\n    dataset = sv.DetectionDataset.from_pascal_voc(images_dir, ann_dir)\nexcept ValueError as e:\n    if 'Could not read image' in str(e):\n        bad = str(e).split('path: ')[-1].strip()\n        # move both image and its xml aside, then retry once\n        Path(bad).rename(bad + '.bad')\n        Path(ann_dir, Path(bad).stem + '.xml').rename(\n            str(Path(ann_dir, Path(bad).stem + '.xml')) + '.bad')\n        dataset = sv.DetectionDataset.from_pascal_voc(images_dir, ann_dir)\n    else:\n        raise","preventionTips":["Verify dataset downloads with checksums or file counts.","Keep images and annotations in matching per-split directories.","Pre-scan with cv2.imread in a bulk check before from_pascal_voc on unfamiliar data."],"tags":["pascal-voc","dataset","opencv","image-io"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}