run-llama/llama_index · error · ValueError

The specified file path is not an accessible image

Error message

The specified file path is not an accessible image

What it means

Document's newer media-resource constructor validates image_path with an image sanity check (is_image_pil). If Pillow cannot open/verify the file at that path — missing, corrupt, or not an image — construction fails immediately with ValueError('The specified file path is not an accessible image').

Source

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

class ImageDocument(Document):
    """Backward compatible wrapper around Document containing an image."""

    def __init__(self, **kwargs: Any) -> None:
        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

View on GitHub (pinned to afd0fef371)

Solutions

1. Verify the path exists, is readable, and is a real image before constructing the Document
2. Pre-open with PIL: Image.open(p).verify() to reproduce and catch the exact failure
3. Skip/quarantine bad files in bulk ingestion instead of aborting the whole run

Example fix

# before
doc = Document(image_path=p, text="photo")  # ValueError on bad file

# after
from PIL import Image
try:
    with Image.open(p) as im:
        im.verify()
    doc = Document(image_path=p, text="photo")
except Exception:
    logger.warning("skipping unreadable image %s", p)

from pathlib import Path
from PIL import Image
p = Path(image_path)
assert p.is_file(), f"missing image: {p}"
with Image.open(p) as im:
    im.verify()  # raises now, not inside Document()

def is_valid_image_file(p: str) -> bool:
    try:
        with Image.open(p) as im:
            im.verify()
        return True
    except Exception:
        return False

try:
    doc = Document(image_path=p, text=caption)
except ValueError:
    logger.warning("skipping unreadable image %s", p)
    continue

When it happens

Trigger: Creating Document(image_path=p) where p does not exist, points to a non-image file, or a corrupt/truncated image; also paths that exist but lack read permission.

Common situations: Bulk-ingesting directories where some files are mislabeled or zero-byte; path bugs (relative vs absolute) when running readers in containers; images in formats Pillow cannot read.

Related errors

• The specified URL 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/d86b33c0ca630257. Report an issue: GitHub.