roboflow/supervision · error · ValueError

Data pointed by URL could not be decoded into image.

Error message

Data pointed by URL could not be decoded into image.

What it means

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.

Source

Thrown at src/supervision/utils/image.py:75

    url_path = urllib.parse.urlparse(value).path
    suffix = Path(url_path).suffix or ".image"
    url_hash = md5(value.encode("utf-8"), usedforsecurity=False).hexdigest()
    return cache_root / f"{url_hash}{suffix}"


def _decode_image_from_bytes(
    value: bytes,
    cv_imread_flags: int,
) -> npt.NDArray[np.uint8]:
    """
    Decode raw image bytes into an OpenCV image, raising on undecodable data.
    """
    image = cv2.imdecode(
        np.frombuffer(value, dtype=np.uint8),
        cv_imread_flags,
    )
    if image is None:
        raise ValueError("Data pointed by URL could not be decoded into image.")

    return cast(npt.NDArray[np.uint8], image)


def load_image_from_url(
    value: str,
    cv_imread_flags: int = cv2.IMREAD_COLOR,
    timeout: float = 30.0,
    use_cache: bool = True,
    cache_dir: str | Path | None = None,
    force_reload: bool = False,
) -> npt.NDArray[np.uint8]:
    """
    Load an image from a URL as an OpenCV image.

    Args:
        value: HTTP(S) URL of the image.
        cv_imread_flags: OpenCV image read flag passed to `cv2.imdecode`.

View on GitHub (pinned to 7f254d9784)

Solutions

1. Open the URL in a browser or with `curl -I` and confirm it returns an image content-type and HTTP 200.
2. If the host requires auth or custom headers, download with `requests` yourself and decode via `cv2.imdecode`.
3. For untrusted URL lists, wrap calls in try/except ValueError and skip/log failures.

Example fix

# before
image = sv.load_image_from_url('https://example.com/photo')  # returns HTML
# after
import requests, cv2, numpy as np
resp = requests.get('https://example.com/photo', timeout=30)
resp.raise_for_status()
image = cv2.imdecode(np.frombuffer(resp.content, np.uint8), cv2.IMREAD_COLOR)

import requests
resp = requests.head(url, timeout=10, allow_redirects=True)
resp.raise_for_status()
ctype = resp.headers.get('content-type', '')
assert ctype.startswith('image/'), f'not an image: {ctype}'

try:
    image = sv.load_image_from_url(url)
except ValueError as e:
    log.warning('undecodable image at %s: %s', url, e)
    continue  # skip bad URL in a scrape loop

When it happens

Trigger: `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.

Common situations: 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.

Related errors

• Downloaded asset {filename} failed MD5 verification.
• Unsupported URL scheme {parsed_url.scheme} in {url}. Only HT
• Invalid URL {url}: no host supplied.
• prepared URL is empty
• Invalid URL {url}: {error}

AI-assisted analysis of roboflow/supervision@7f254d9784 (2026-08-15). Data as JSON: /api/errors/fef1983360df4b09. Report an issue: GitHub.