zylon-ai/private-gpt · error · ValueError

Failed to describe images in the message.

Error message

Failed to describe images in the message.

What it means

Image preprocessor counterpart of error 55: process_images_in_message completed but returned an empty/falsy description for images present in the message. Rather than continuing with a blank 'we processed these images' payload, the processor raises to signal the vision step effectively failed.

Source

Thrown at private_gpt/components/chat/processors/chat_history/multimodality/image_preprocessor.py:70

    image_blocks = extract_image_blocks(message)
    if not image_blocks:
        yield ImageProcessingResponse(message=message)
        return

    if image_multimodal_llm is None:
        raise ValueError("Image blocks found but no image-capable LLM provided.")

    event = MultimodalProcessingStatus(status="processing", type="image")
    yield ImageProcessingResponse(processing_status=event)

    try:
        image_description = await process_images_in_message(
            image_multimodal_llm, message, user_query=message.content, **kwargs
        )

        if not image_description:
            raise ValueError("Failed to describe images in the message.")

        event = event.model_copy(
            update={
                "status": "completed",
                "content": image_description,
            }
        )
        yield ImageProcessingResponse(processing_status=event)
        final_message = (
            "The user has included images in their message. "
            "We have processed these images and obtained the following descriptions:\n"
            f"{image_description}"
        )

    except Errors.RequestTooLarge as e:
        event = event.model_copy(
            update={
                "status": "failed",

View on GitHub (pinned to 4a030776a3)

Solutions

1. Retry once — transient empty completions are common under load
2. Inspect the raw vision LLM response for the image that fails; test the image directly
3. Validate/normalize images (format, size, corruption) before the LLM call
4. Wrap with a fallback description if empty results are acceptable in your flow

Example fix

# before
image_description = await process_images_in_message(llm, message, user_query=...)

# after
image_description = await process_images_in_message(llm, message, user_query=...)
if not image_description:
    image_description = "(image content could not be described)"

def is_describable_image(block) -> bool:
    return block_has_valid_image_data(block)  # decodes, checks non-zero size/format

try:
    async for resp in image_preprocessor.run(message, ...):
        ...
except ValueError as e:
    if "Failed to describe images" in str(e):
        async for resp in image_preprocessor.run(message, ...):  # one retry
            ...
    else:
        raise

When it happens

Trigger: Calling the image preprocessor with ImageBlock content where the vision LLM returns empty text (empty completion, content filter, wrong output parsing).

Common situations: Vision model refusing or returning empty for problematic images (corrupt file, unsupported aspect, pure black frame); response-schema mismatch dropping the description field; overloaded inference server returning empty bodies.

Related errors

• Failed to describe audio in the message.
• Audio blocks found but no audio-capable LLM provided.
• No items returned from astream_structured_predict
• No items returned from astream_structured_chat
• LLM does not support structured chat.

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/5e5fe667c0d43bb6. Report an issue: GitHub.