run-llama/llama_index · error · ValueError

The provided image string is not base64-encoded

Error message

The provided image string is not base64-encoded

What it means

Raised by image_node_to_image_block when ImageNode.image is a string that fails strict base64 decoding (base64.b64decode with validate=True raising BinasciiError). The string must be valid base64-encoded image bytes, not a path or URL.

Source

Thrown at llama-index-core/llama_index/core/base/llms/generic_utils.py:350

def image_node_to_image_block(image_node: ImageNode) -> ImageBlock:
    """
    Get an ImageBlock from an ImageNode.

    Args:
        image_node (ImageNode): ImageNode to convert.

    Returns:
        ImageBlock: block representation of the node.

    Raises:
        ValueError: when the image provided within the ImageNode is not correctly base64-encoded.

    """
    if isinstance(image_node.image, str):
        try:
            return ImageBlock(image=base64.b64decode(image_node.image, validate=True))
        except BinasciiError:
            raise ValueError("The provided image string is not base64-encoded")
    elif image_node.image is None:
        if image_node.image_path is not None:
            image_path: Optional[Path] = Path(image_node.image_path)
        elif "file_path" in image_node.metadata:
            image_path = image_node.metadata["file_path"]
        else:
            image_path = image_node.image_path
        return ImageBlock(
            image=image_node.image,
            url=image_node.image_url,
            image_mimetype=image_node.image_mimetype,
            path=image_path,
        )

    else:
        raise ValueError("image_node.image is neither a string or None.")

View on GitHub (pinned to afd0fef371)

Solutions

1. If the string is a path, set image_path=... (or metadata['file_path']) and leave image=None instead.
2. If it's a URL, set image_url=... instead of image=.
3. If it is meant to be raw base64, strip prefixes/whitespace and re-encode the source bytes correctly (base64.b64encode(open(p,'rb').read()).decode()).

Example fix

# before
node = ImageNode(image="/data/cat.png")
block = image_node_to_image_block(node)

# after
node = ImageNode(image_path="/data/cat.png")
block = image_node_to_image_block(node)

import base64, binascii
try:
    base64.b64decode(s, validate=True)
    is_b64 = True
except (binascii.Error, ValueError):
    is_b64 = False
node = ImageNode(image=s) if is_b64 else ImageNode(image_path=s)

def looks_like_base64(s: str) -> bool:
    import base64, binascii
    try:
        base64.b64decode(s, validate=True)
        return True
    except (binascii.Error, ValueError):
        return False

When it happens

Trigger: Building an ImageBlock from an ImageNode whose .image was set to a file path, a URL, or malformed/padded base64; truncated base64 from a DB or JSON round-trip.

Common situations: Setting ImageNode(image="/tmp/photo.png") intending a path; whitespace or data:image/png;base64, prefixes embedded in the string; copy-paste truncation of base64 payloads.

Related errors

• image_node.image is neither a string or None.
• resolve_image returned zero bytes
• LLM only supports text inputs
• Could not format attribute {attribute_name} with value {temp
• resolve_audio returned zero bytes

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