{"record":{"id":"c0761c17eb73373c","repo":"roboflow/supervision","slug":"could-not-read-image-from-path-image-path","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/core.py","lineNumber":155,"sourceCode":"        # Eliminate duplicates while preserving order\n        self.image_paths = list(dict.fromkeys(images))\n\n        self._images_in_memory: dict[str, npt.NDArray[np.uint8]] = {}\n        if isinstance(images, dict):\n            self._images_in_memory = images\n            warn_deprecated(\n                \"Passing a `Dict[str, np.ndarray]` into `DetectionDataset` is \"\n                \"deprecated in `0.30.0` and will be removed in `0.33.0`. Use \"\n                \"a list of paths `List[str]` instead.\"\n            )\n\n    def _get_image(self, image_path: str) -> npt.NDArray[np.uint8]:\n        \"\"\"Assumes that image is in dataset.\"\"\"\n        if self._images_in_memory:\n            return self._images_in_memory[image_path]\n        image = cv2.imread(image_path)\n        if image is None:\n            raise ValueError(f\"Could not read image from path: {image_path}\")\n        return cast(npt.NDArray[np.uint8], image)\n\n    def __len__(self) -> int:\n        return len(self._images_in_memory) or len(self.image_paths)\n\n    def __getitem__(self, i: int) -> tuple[str, npt.NDArray[np.uint8], Detections]:\n        \"\"\"\n        Returns:\n            The image path, image data,\n                and its corresponding annotation at index i.\n        \"\"\"\n        image_path = self.image_paths[i]\n        image = self._get_image(image_path)\n        annotation = self.annotations[image_path]\n        return image_path, image, annotation\n\n    def __iter__(self) -> Iterator[tuple[str, npt.NDArray[np.uint8], Detections]]:\n        \"\"\"","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/dataset/core.py#L137-L173","documentation":"Raised by DetectionDataset._get_image when cv2.imread returns None for a lazy (path-based) dataset. OpenCV returns None — rather than raising — for nonexistent paths, unreadable/corrupt files, unsupported formats, or non-ASCII paths on some platforms, so supervision converts that into an explicit ValueError naming the path.","triggerScenarios":"Accessing ds[i] (or iterating) on a path-based DetectionDataset where an image path no longer exists, points outside the dataset root (relative paths resolved from the wrong cwd), or the file is corrupted/not a decodable image.","commonSituations":"Relative image paths resolved from a different working directory; dataset moved/archived after construction; 0-byte or truncated downloads; EXR/HEIC files OpenCV cannot decode without plugins.","solutions":["Check the path exists and is absolute before dataset construction: Path(p).resolve() on all image_paths.","Run from the directory the paths were built relative to, or normalize with os.path.abspath.","Pre-validate decodability with cv2.imread(p) is not None and drop/repair failing entries.","If files were moved, reconstruct the dataset with updated paths."],"exampleFix":"// before\npaths = glob('images/*.jpg')  # relative\nds = DetectionDataset(classes=c, images=paths, annotations=anns)\nitem = ds[0]  # run from another cwd -> ValueError\n\n// after\nfrom pathlib import Path\npaths = [str(Path(p).resolve()) for p in glob('images/*.jpg')]\nds = DetectionDataset(classes=c, images=paths, annotations=anns)","handlingStrategy":"validation","validationCode":"bad = [p for p in ds.image_paths if not Path(p).is_file() or cv2.imread(p) is None]\nif bad:\n    raise FileNotFoundError(f\"Unreadable images: {bad}\")\nitem = ds[0]","typeGuard":null,"tryCatchPattern":"try:\n    _, img, dets = ds[i]\nexcept ValueError as e:\n    if \"Could not read image\" in str(e):\n        # re-locate the file or rebuild dataset without it\n        raise\n    raise","preventionTips":["Store absolute paths in datasets: [str(Path(p).resolve()) for p in paths].","Pre-validate readability with cv2.imread before constructing the dataset.","Avoid changing working directory between dataset construction and iteration."],"tags":["dataset","opencv","image-io","path"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}