{"record":{"id":"fef1983360df4b09","repo":"roboflow/supervision","slug":"data-pointed-by-url-could-not-be-decoded-into-imag","errorCode":null,"errorMessage":"Data pointed by URL could not be decoded into image.","messagePattern":"Data pointed by URL could not be decoded into image\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/utils/image.py","lineNumber":75,"sourceCode":"    url_path = urllib.parse.urlparse(value).path\n    suffix = Path(url_path).suffix or \".image\"\n    url_hash = md5(value.encode(\"utf-8\"), usedforsecurity=False).hexdigest()\n    return cache_root / f\"{url_hash}{suffix}\"\n\n\ndef _decode_image_from_bytes(\n    value: bytes,\n    cv_imread_flags: int,\n) -> npt.NDArray[np.uint8]:\n    \"\"\"\n    Decode raw image bytes into an OpenCV image, raising on undecodable data.\n    \"\"\"\n    image = cv2.imdecode(\n        np.frombuffer(value, dtype=np.uint8),\n        cv_imread_flags,\n    )\n    if image is None:\n        raise ValueError(\"Data pointed by URL could not be decoded into image.\")\n\n    return cast(npt.NDArray[np.uint8], image)\n\n\ndef load_image_from_url(\n    value: str,\n    cv_imread_flags: int = cv2.IMREAD_COLOR,\n    timeout: float = 30.0,\n    use_cache: bool = True,\n    cache_dir: str | Path | None = None,\n    force_reload: bool = False,\n) -> npt.NDArray[np.uint8]:\n    \"\"\"\n    Load an image from a URL as an OpenCV image.\n\n    Args:\n        value: HTTP(S) URL of the image.\n        cv_imread_flags: OpenCV image read flag passed to `cv2.imdecode`.","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/utils/image.py#L57-L93","documentation":"Raised by `load_image_from_url` (via `_decode_image_from_bytes`) when `cv2.imdecode` returns None for the downloaded bytes, meaning the payload is not a decodable image. Common causes: the URL returns an HTML error page (404/403), a redirect to a login page, or a non-image content type. The check distinguishes 'download succeeded but content is not an image' from network failures.","triggerScenarios":"`sv.load_image_from_url('https://example.com/missing.jpg')` where the server returns an HTML 404 page; a URL requiring auth headers; a file served as text/plain; truncated download of a large image.","commonSituations":"Scraping datasets where some links are dead or redirect; CDN URLs behind rate limits returning XML error bodies; corporate proxies injecting HTML interstitials; URLs with query strings that serve dynamic content.","solutions":["Open the URL in a browser or with `curl -I` and confirm it returns an image content-type and HTTP 200.","If the host requires auth or custom headers, download with `requests` yourself and decode via `cv2.imdecode`.","For untrusted URL lists, wrap calls in try/except ValueError and skip/log failures."],"exampleFix":"# before\nimage = sv.load_image_from_url('https://example.com/photo')  # returns HTML\n# after\nimport requests, cv2, numpy as np\nresp = requests.get('https://example.com/photo', timeout=30)\nresp.raise_for_status()\nimage = cv2.imdecode(np.frombuffer(resp.content, np.uint8), cv2.IMREAD_COLOR)","handlingStrategy":"try-catch","validationCode":"import requests\nresp = requests.head(url, timeout=10, allow_redirects=True)\nresp.raise_for_status()\nctype = resp.headers.get('content-type', '')\nassert ctype.startswith('image/'), f'not an image: {ctype}'","typeGuard":null,"tryCatchPattern":"try:\n    image = sv.load_image_from_url(url)\nexcept ValueError as e:\n    log.warning('undecodable image at %s: %s', url, e)\n    continue  # skip bad URL in a scrape loop","preventionTips":["Verify URLs return image content-type before batch processing.","Handle auth-requiring hosts with explicit requests calls.","In scrapers, always wrap per-URL so one bad link does not kill the run."],"tags":["image","url","download","decode","network"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}