microsoft/semantic-kernel · error · ValueError

ImageContent must have either a data_uri or uri set to be us

Error message

ImageContent must have either a data_uri or uri set to be used in the request.

What it means

Raised as a ValueError when serializing chat history for a Responses request, an ImageContent item is encountered that has neither a data_uri nor a uri. The serializer (_prepare_chat_history_for_request) needs a URL or data URI to build the input_image payload; with neither, it cannot construct a valid request, so it fails fast.

Source

Thrown at python/semantic_kernel/agents/open_ai/responses_agent_thread_actions.py:819

                match content:
                    case TextContent() | StreamingTextContent():
                        final_text = content.text
                        if not isinstance(final_text, str):
                            if isinstance(final_text, (list, tuple)):
                                final_text = " ".join(map(str, final_text))
                            else:
                                final_text = str(final_text)
                        text_type = "input_text" if original_role == AuthorRole.USER else "output_text"
                        contents.append({"type": text_type, "text": final_text})
                    case ImageContent():
                        image_url = ""
                        if content.data_uri:
                            image_url = content.data_uri
                        elif content.uri:
                            image_url = str(content.uri)

                        if not image_url:
                            raise ValueError(
                                "ImageContent must have either a data_uri or uri set to be used in the request."
                            )

                        contents.append({"type": "input_image", "image_url": image_url})
                    case FunctionCallContent():
                        if not store_enabled:
                            fc_dict = {
                                "type": "function_call",
                                "call_id": content.call_id,
                                "name": content.name,
                                "arguments": content.arguments,
                            }
                            response_inputs.append(fc_dict)
                    case FunctionResultContent():
                        rfrc_dict = {
                            "type": "function_call_output",
                            "output": str(content.result),
                            "call_id": content.call_id,

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Ensure every ImageContent has a data_uri (base64) or a resolvable uri before adding it to chat history.
2. For local files, use the helper to build a data URI: ImageContent.from_image_file(path) or encode bytes as a data URI.
3. Validate image content before sending: assert content.data_uri or content.uri.
4. Filter out empty/placeholder image items before invoking the agent.

Example fix

# before
from semantic_kernel.contents import ImageContent
msg = ChatMessageContent(role=AuthorRole.USER, items=[
    ImageContent(),  # no data_uri or uri -> error
])
# after - provide a data URI
msg = ChatMessageContent(role=AuthorRole.USER, items=[
    ImageContent(data_uri="data:image/png;base64,iVBORw0KG..."),
])

# Validate image content before adding to chat history:
def assert_image_usable(content):
    if not (content.data_uri or content.uri):
        raise ValueError("ImageContent needs a data_uri or uri")
for msg in chat_history:
    for item in msg.items:
        if type(item).__name__ == "ImageContent":
            assert_image_usable(item)

from semantic_kernel.contents import ImageContent
def has_image_source(content: ImageContent) -> bool:
    return bool(getattr(content, "data_uri", None) or getattr(content, "uri", None))

try:
    async for _, m in agent.invoke(thread=thread):
        ...
except ValueError as ex:
    if "ImageContent" in str(ex):
        # remove/fix the offending image item and retry
        ...

When it happens

Trigger: A ChatMessageContent containing an ImageContent item with both data_uri and uri empty/None is passed into the agent's chat history. Occurs when constructing images manually (e.g. ImageContent(data_uri=None, uri=None)) or when an image was created but its source was never set.

Common situations: Building ImageContent from a local file but forgetting to call to_uri()/encode it to a data URI; placeholders/empty image content objects left in the history; copying an ImageContent and losing the uri; loading images from a source that returned None.

Related errors

• Image content does not contain any data or uri.
• Image content MimeType is empty.
• ImageContent in function result must contain binary data.
• The process must have an Id set
• The edge target is not a function target: {e.OutputTarget}

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