{"record":{"id":"b69ac107efe08210","repo":"roboflow/supervision","slug":"error-couldn-t-load-the-icon-image-from-icon-pat","errorCode":null,"errorMessage":"Error: Couldn't load the icon image from {icon_path}","messagePattern":"Error: Couldn't load the icon image from (.+?)","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"src/supervision/annotators/core.py","lineNumber":64,"sourceCode":"from supervision.utils.image import (\n    _overlay_image,\n    crop_image,\n    letterbox_image,\n    scale_image,\n)\nfrom supervision.utils.logger import _get_logger\n\nlogger = _get_logger(__name__)\n\n\n@lru_cache\ndef _load_icon_from_path(\n    icon_path: str, icon_resolution_wh: tuple[int, int]\n) -> npt.NDArray[np.uint8]:\n    \"\"\"Load and resize an icon image through a cache shared by annotators.\"\"\"\n    icon = cv2.imread(icon_path, cv2.IMREAD_UNCHANGED)\n    if icon is None:\n        raise FileNotFoundError(f\"Error: Couldn't load the icon image from {icon_path}\")\n    icon_array = cast(npt.NDArray[np.uint8], icon)\n    result: npt.NDArray[np.uint8] = letterbox_image(\n        image=icon_array, resolution_wh=icon_resolution_wh\n    )\n    return result\n\n\ndef _normalize_color_input(color: Color | ColorPalette | str) -> Color | ColorPalette:\n    \"\"\"Normalize accepted color inputs to internal color objects.\n\n    Accepts `Color`, `ColorPalette`, or hex string input. Hex strings are parsed via\n    `hex_to_rgba` and converted to `Color` (alpha channel is ignored because annotator\n    drawing uses RGB/BGR colors).\n    \"\"\"\n    if isinstance(color, str):\n        r, g, b, _ = hex_to_rgba(color)\n        return Color.from_rgb_tuple((r, g, b))\n    return color","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/annotators/core.py#L46-L82","documentation":"Raised by the cached icon loader used by `IconAnnotator` when `cv2.imread` returns None for the given path — i.e. the file does not exist, is unreadable, or is not a decodable image. OpenCV silently returns None for unreadable files, so supervision converts that into an explicit FileNotFoundError with the offending path.","triggerScenarios":"Calling `IconAnnotator(icon_path=\"icons/warning.png\").annotate(...)` when the file is absent; passing a path with a leading '~' (not expanded by cv2.imread); a non-image or corrupted file; a path that exists inside a container but was not mounted/copied into the image.","commonSituations":"Relative paths resolved against a different working directory (script run from another folder); deploying to Docker where asset icons were not copied into the image; Windows/POSIX path separators in shared code; downloading icons at runtime and racing against the download.","solutions":["Verify the path exists with `pathlib.Path(icon_path).resolve()` and expand `~` with `expanduser()` before passing it.","Use absolute paths anchored to your project root (e.g. `Path(__file__).parent / 'icons/warning.png'`).","If icons are downloaded at runtime, wait for the download to complete and validate the file is a decodable image before annotating."],"exampleFix":"# before\nannotator = sv.IconAnnotator(icon_path=\"~/assets/alert.png\")  # '~' not expanded\n\n# after\nfrom pathlib import Path\nicon = Path(\"~/assets/alert.png\").expanduser().resolve()\nassert icon.is_file(), f\"missing icon: {icon}\"\nannotator = sv.IconAnnotator(icon_path=str(icon))","handlingStrategy":"validation","validationCode":"from pathlib import Path\nimport cv2\n\nicon = Path(icon_path).expanduser().resolve()\nassert icon.is_file(), f\"icon not found: {icon}\"\nassert cv2.imread(str(icon)) is not None, f\"icon not decodable: {icon}\"\nannotator = sv.IconAnnotator(icon_path=str(icon))","typeGuard":null,"tryCatchPattern":"try:\n    annotator.annotate(scene, detections)\nexcept FileNotFoundError as e:\n    logger.error(\"icon asset missing, skipping annotation: %s\", e)\n    # fallback: annotate without icons, do not crash the pipeline","preventionTips":["Anchor icon paths to the project root with Path(__file__).parent, not cwd.","Expand ~ and verify is_file() once at annotator construction.","Copy icon assets into Docker images or mount their directory."],"tags":["filesystem","annotators","icons"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}