run-llama/llama_index · error · ValueError

The specified URL is not an accessible image

Error message

The specified URL is not an accessible image

What it means

Document's media-resource constructor validates image_url by checking the URL is an accessible image (is_image_url_pil). If the URL is malformed, unreachable, returns a non-image (HTML error page, 404), or the payload is not a valid image, construction raises ValueError('The specified URL is not an accessible image').

Source

Thrown at llama-index-core/llama_index/core/schema.py:1352

        image = kwargs.pop("image", None)
        image_path = kwargs.pop("image_path", None)
        image_url = kwargs.pop("image_url", None)
        image_mimetype = kwargs.pop("image_mimetype", None)
        text_embedding = kwargs.pop("text_embedding", None)

        if image:
            kwargs["image_resource"] = MediaResource(
                data=image, mimetype=image_mimetype
            )
        elif image_path:
            if not is_image_pil(image_path):
                raise ValueError("The specified file path is not an accessible image")
            kwargs["image_resource"] = MediaResource(
                path=image_path, mimetype=image_mimetype
            )
        elif image_url:
            if not is_image_url_pil(image_url):
                raise ValueError("The specified URL is not an accessible image")
            kwargs["image_resource"] = MediaResource(
                url=image_url, mimetype=image_mimetype
            )

        super().__init__(**kwargs)

    @property
    def image(self) -> str | None:
        if self.image_resource and self.image_resource.data:
            return self.image_resource.data.decode("utf-8")
        return None

    @image.setter
    def image(self, image: str) -> None:
        self.image_resource = MediaResource(data=image.encode("utf-8"))

    @property
    def image_path(self) -> str | None:

View on GitHub (pinned to afd0fef371)

Solutions

1. Check the URL first: requests.head(u) expecting status 200 and an image/* content-type
2. Fix or refresh expired/signed URLs before ingestion
3. Download the bytes yourself and pass image= (base64) so you control errors and retries

Example fix

# before
doc = Document(image_url=url)  # ValueError on 404/HTML

# after
import requests
resp = requests.head(url, timeout=10, allow_redirects=True)
if resp.ok and resp.headers.get("content-type", "").startswith("image/"):
    doc = Document(image_url=url)
else:
    raise RuntimeError(f"bad image url {url}: {resp.status_code}")

import requests
r = requests.head(url, timeout=10, allow_redirects=True)
ok = r.ok and r.headers.get("content-type", "").startswith("image/")

def is_fetchable_image_url(u: str) -> bool:
    try:
        r = requests.head(u, timeout=10, allow_redirects=True)
        return r.ok and r.headers.get("content-type", "").startswith("image/")
    except requests.RequestException:
        return False

try:
    doc = Document(image_url=url)
except ValueError:
    # download bytes yourself and pass image=base64 instead
    ...

When it happens

Trigger: Creating Document(image_url=u) where u returns 404/403, points to an HTML page, is an unsupported format, or the host is unreachable/slow (network egress blocked in containers).

Common situations: Scraped URLs that expired or redirect to login pages; signed S3/CDN URLs that expired; running in sandboxes without network access; URLs with trailing spaces or missing scheme.

Related errors

• The specified file path is not an accessible image
• No image found in node.
• No image found in the chat message!
• Cannot initialize from a vector store that does not store te
• Must provide either prompt or prompt_template_str.

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/c9e05c487adc1ee6. Report an issue: GitHub.