run-llama/llama_index · error · ValueError

image_node.image is neither a string or None.

Error message

image_node.image is neither a string or None.

What it means

Raised by image_node_to_image_block when ImageNode.image is neither a str nor None (e.g. bytes, dict, or PIL object). The function only understands base64-string or absent image data; other binary representations are rejected.

Source

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

            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 you have raw bytes, base64-encode them: image=base64.b64encode(raw).decode('utf-8').
2. If the data lives on disk or remotely, use image_path= or image_url= and keep image=None.
3. Add a construction-time check that image is None or a valid base64 str before creating ImageNodes.

Example fix

# before
node = ImageNode(image=open('cat.png','rb').read())

# after
import base64
node = ImageNode(image=base64.b64encode(open('cat.png','rb').read()).decode())
# or simpler: node = ImageNode(image_path='cat.png')

assert image_node.image is None or isinstance(image_node.image, str), "image must be base64 str or None"

def is_valid_image_value(v: Any) -> bool:
    return v is None or isinstance(v, str)

When it happens

Trigger: Setting ImageNode(image=open('x.png','rb').read()) (raw bytes), image=PIL.Image, or image=bytearray and then calling image_node_to_image_block.

Common situations: Reading files as bytes and assigning directly to .image; interop code that stores decoded bytes from another pipeline; assuming bytes are accepted because the field is loosely typed.

Related errors

• The provided image string is not base64-encoded
• resolve_image returned zero bytes
• Unexpected type: {type(choice)}
• Unexpected type: {type(query)}
• embeddings_cache must be of type BaseKVStore

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