run-llama/llama_index · error · ValueError

resolve_image returned zero bytes

Error message

resolve_image returned zero bytes

What it means

Raised by ImageBlock.resolve_image(as_base64=...) when the resolved data buffer contains zero bytes after resolving from raw bytes, path, or URL. The block guards against sending empty image payloads to APIs that would otherwise fail cryptically.

Source

Thrown at llama-index-core/llama_index/core/base/llms/types.py:391

        """
        data_buffer = (
            self.image
            if isinstance(self.image, IOBase)
            else resolve_binary(
                raw_bytes=self.image,
                path=self.path,
                url=str(self.url) if self.url else None,
                as_base64=as_base64,
            )
        )

        # Check size by seeking to end and getting position
        data_buffer.seek(0, 2)  # Seek to end
        size = data_buffer.tell()
        data_buffer.seek(0)  # Reset to beginning

        if size == 0:
            raise ValueError("resolve_image returned zero bytes")
        return data_buffer

    def inline_url(self) -> str:
        b64 = self.resolve_image(as_base64=True)
        b64_str = b64.read().decode("utf-8")
        return f"data:{self.image_mimetype};base64,{b64_str}"

    async def aestimate_tokens(self, *args: Any, **kwargs: Any) -> int:
        """
        Many APIs measure images differently. Here, we take a large estimate.

        This is based on a 2048 x 1536 image using OpenAI.

        TODO: In the future, LLMs should be able to count their own tokens.
        """
        try:
            self.resolve_image()
            return 2125

View on GitHub (pinned to afd0fef371)

Solutions

1. Check the source before constructing the block: os.path.getsize(path) > 0, len(image_bytes) > 0.
2. Fetch and validate the URL content-length/bytes yourself before assigning url=, or catch this error and retry the download.
3. Fix the upstream producer writing empty files/records.

Example fix

# before
block = ImageBlock(path="downloaded.png")  # file is 0 bytes
data = block.resolve_image(as_base64=True).read()

# after
import os
if os.path.getsize("downloaded.png") == 0:
    raise RuntimeError("empty download, refetching")
block = ImageBlock(path="downloaded.png")

import os
ok = (image_bytes and len(image_bytes) > 0) or (path and os.path.getsize(path) > 0)
if not ok:
    raise ValueError("image source is empty")

try:
    buf = block.resolve_image(as_base64=True)
except ValueError as e:
    if "zero bytes" in str(e):
        refetch_or_skip()  # re-download or skip record
    else:
        raise

When it happens

Trigger: ImageBlock with an empty image=b"" value; a path pointing at a 0-byte file; a URL that returns an empty response body (200 with empty content); a failed download silently yielding b''.

Common situations: Upstream write producing empty files; signed URLs expiring and returning empty bodies; placeholder records with empty image bytes in a database; network interception returning empty 200s.

Related errors

• The provided image string is not base64-encoded
• image_node.image is neither a string or None.
• resolve_audio returned zero bytes
• resolve_video returned zero bytes
• resolve_document returned zero bytes

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