{"record":{"id":"78b768e580ba6d24","repo":"roboflow/supervision","slug":"image-path-image-does-not-exist","errorCode":null,"errorMessage":"Image path ('{image}') does not exist.","messagePattern":"Image path \\('(.+?)'\\) does not exist\\.","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"src/supervision/draw/utils.py","lineNumber":439,"sourceCode":"    Example:\n        ```pycon\n        >>> import numpy as np\n        >>> from supervision.draw.utils import draw_image\n        >>> from supervision.geometry.core import Rect\n        >>> scene = np.zeros((100, 100, 3), dtype=np.uint8)\n        >>> image = np.full((40, 40, 3), 255, dtype=np.uint8)\n        >>> rect = Rect(x=10, y=10, width=40, height=40)\n        >>> scene = draw_image(scene, image, opacity=0.8, rect=rect)\n        >>> scene.shape\n        (100, 100, 3)\n\n        ```\n    \"\"\"\n\n    # Validate and load image\n    if isinstance(image, str):\n        if not os.path.exists(image):\n            raise FileNotFoundError(f\"Image path ('{image}') does not exist.\")\n        loaded_image = cv2.imread(image, cv2.IMREAD_UNCHANGED)\n        if loaded_image is None:\n            raise OSError(f\"Could not decode image path ('{image}').\")\n        image_np = cast(npt.NDArray[np.uint8], loaded_image)\n    else:\n        image_np = image\n\n    if image_np.ndim != 3 or image_np.shape[2] not in (3, 4):\n        raise ValueError(\"Image must have 3 or 4 channels.\")\n\n    # Validate opacity\n    if not 0.0 <= opacity <= 1.0:\n        raise ValueError(\"Opacity must be between 0.0 and 1.0.\")\n\n    rect_x = int(rect.x)\n    rect_y = int(rect.y)\n    rect_width = int(rect.width)\n    rect_height = int(rect.height)","sourceCodeStart":421,"sourceCodeEnd":457,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/draw/utils.py#L421-L457","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use an absolute path: Path(__file__).parent / 'assets' / 'logo.png'","Verify existence in your loader: if not p.is_file(): raise with a clear message","Load the image yourself (cv2.imread) and pass the ndarray, keeping file handling in your code"],"exampleFix":"# before\nscene = draw_image(scene, 'assets/logo.png', opacity=0.8, rect=rect)  # CWD-dependent\n\n# after\nfrom pathlib import Path\nlogo_path = Path(__file__).parent / 'assets' / 'logo.png'\nscene = draw_image(scene, str(logo_path), opacity=0.8, rect=rect)","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\nlogo_path = Path(logo_path)\nif not logo_path.is_file():\n    raise FileNotFoundError(f'logo asset missing: {logo_path}')\nscene = draw_image(scene, str(logo_path), opacity=0.8, rect=rect)","typeGuard":"from pathlib import Path\n\ndef is_readable_file(path: object) -> bool:\n    \"\"\"True when path is an existing file Path/str.\"\"\"\n    return isinstance(path, (str, Path)) and Path(path).is_file()","tryCatchPattern":"try:\n    scene = draw_image(scene, str(logo_path), opacity=0.8, rect=rect)\nexcept FileNotFoundError as e:\n    # fall back to a bundled asset or skip drawing\n    if (fallback := Path(__file__).parent / 'assets' / 'logo.png').is_file():\n        scene = draw_image(scene, str(fallback), opacity=0.8, rect=rect)\n    else:\n        raise","preventionTips":["Resolve asset paths against the module: Path(__file__).parent / 'assets'","Include drawn assets in Docker/packager builds and verify at startup"],"tags":["drawing","file-io","path","file-not-found"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}