microsoft/semantic-kernel · error · ValueError

Image item must contain data encoded as base64.

Error message

Image item must contain data encoded as base64.

What it means

Raised inside _format_user_message when a user message contains an ImageContent item whose .data attribute is falsy (None or empty string). The Ollama API requires base64-encoded image data for inline images; the formatter checks all image items and rejects the request if any lack data. Note this is a plain ValueError, not a ServiceException.

Source

Thrown at python/semantic_kernel/connectors/ai/ollama/services/utils.py:51

def _format_user_message(message: ChatMessageContent) -> Message:
    """Format a user message to the expected object for the client.

    Args:
        message: The user message.

    Returns:
        The formatted user message.
    """
    if not any(isinstance(item, (ImageContent)) for item in message.items):
        return Message(role="user", content=message.content)

    user_message = Message(role="user", content=message.content)

    image_items = [item for item in message.items if isinstance(item, ImageContent)]
    if image_items:
        if any(not image_item.data for image_item in image_items):
            raise ValueError("Image item must contain data encoded as base64.")
        user_message["images"] = [image_item.data for image_item in image_items]

    return user_message


def _format_assistant_message(message: ChatMessageContent) -> Message:
    """Format an assistant message to the expected object for the client.

    Args:
        message: The assistant message.

    Returns:
        The formatted assistant message.
    """
    assistant_message = Message(role="assistant", content=message.content)

    image_items = [item for item in message.items if isinstance(item, ImageContent)]
    if image_items:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Provide base64-encoded data when creating the ImageContent
2. Read the image file and encode it: ImageContent(data=base64.b64encode(open('img.png','rb').read()).decode())
3. If using a file path, pre-load and encode the data before adding to the message

Example fix

// before
ImageContent(uri='file:///img.png')
// after
import base64
ImageContent(data=base64.b64encode(open('img.png','rb').read()).decode())

from semantic_kernel.contents import ImageContent

def validate_image_items(message):
    for item in message.items:
        if isinstance(item, ImageContent) and not item.data:
            raise ValueError(f'ImageContent at index is missing base64 data')

validate_image_items(user_message)

from semantic_kernel.contents import ImageContent

def has_valid_image_data(message) -> bool:
    return all(
        item.data for item in message.items
        if isinstance(item, ImageContent)
    )

try:
    response = await chat.get_chat_message_contents(chat_history=history, settings=settings)
except ValueError as e:
    if 'data encoded as base64' in str(e):
        logger.error('User message contains an image without base64 data')
        raise

When it happens

Trigger: Adding an ImageContent to a user message without base64 data — e.g. ImageContent(uri='file:///img.png') with no data field, or ImageContent() with data left as None. Triggered when the message is formatted for an Ollama chat or text request.

Common situations: Creating ImageContent from a URI but forgetting to read and base64-encode the file; using a constructor that sets uri but not data; loading image metadata from a database without populating the data field.

Related errors

• Image must be encoded as base64.
• Tool message must have a function result content item.
• Please provide valid Ollama configuration in appsettings.Dev
• ImageContent cannot be converted to ResponseContentPart. Onl
• Image content URI is empty.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/94e41cea4ee853e2. Report an issue: GitHub.