invoke-ai/InvokeAI · warning · ValueError

{len(images)} images were provided as input to the LLaVA One

Error message

{len(images)} images were provided as input to the LLaVA OneVision model. Pass <=3 images for good performance.

What it means

run() of the LLaVA OneVision image-to-prompt pipeline enforces a soft limit of 3 input images per call; beyond that, multi-image performance (and prompt formatting) degrades badly, so it raises ValueError up front instead of producing poor output.

Source

Thrown at invokeai/backend/llava_onevision_pipeline.py:44

class LlavaOnevisionPipeline:
    """A wrapper for a LLaVA Onevision model + processor."""

    def __init__(self, vllm_model: LlavaOnevisionForConditionalGeneration, processor: LlavaOnevisionProcessor):
        self._vllm_model = vllm_model
        self._processor = processor

    def run(
        self,
        prompt: str,
        images: list[Image],
        device: torch.device,
        dtype: torch.dtype,
        max_new_tokens: int = 400,
        progress_callback: ProgressCallback | None = None,
    ) -> str:
        # TODO(ryand): Tune the max number of images that are useful for the model.
        if len(images) > 3:
            raise ValueError(
                f"{len(images)} images were provided as input to the LLaVA OneVision model. "
                "Pass <=3 images for good performance."
            )

        # Define a chat history and use `apply_chat_template` to get correctly formatted prompt.
        # "content" is a list of dicts with types "text" or "image".
        content = [{"type": "text", "text": prompt}]
        for _ in images:
            content.append({"type": "image"})

        conversation = [{"role": "user", "content": content}]
        formatted_prompt = self._processor.apply_chat_template(conversation, add_generation_prompt=True)
        inputs = self._processor(images=images or None, text=formatted_prompt, return_tensors="pt").to(
            device=device, dtype=dtype
        )

        tokenizer = self._processor.tokenizer
        streamer = TextIteratorStreamer(tokenizer, skip_prompt=True, skip_special_tokens=True, timeout=STREAM_TIMEOUT)

View on GitHub (pinned to 0b6a024f2f)

Solutions

Split the input into chunks of at most 3 images and call run() once per chunk (or once per image).
Cap the number of images at the UI/batch layer before invoking the pipeline.
If you need many images described, run them sequentially and merge the prompts.
Use a dedicated multi-image model/batch API if >3 images per inference is a hard requirement.

Example fix

// before
prompt = pipeline.run(images=all_12_images, ...)
// after
prompts = [pipeline.run(images=all_12_images[i:i+3], ...) for i in range(0, len(all_12_images), 3)]

Defensive patterns

Strategy: validation

Validate before calling

if len(images) > 3:
    raise ValueError(f'{len(images)} images given; LLaVA OneVision pipeline accepts at most 3 per run() call')

Type guard

def is_valid_image_batch(images) -> bool:
    return isinstance(images, (list, tuple)) and 0 < len(images) <= 3

Try / catch

try:
    prompt = pipeline.run(images, dtype=dtype)
except ValueError as e:
    if 'Pass <=3 images' in str(e):
        prompts = [pipeline.run(images[i:i+3], dtype=dtype) for i in range(0, len(images), 3)]
        prompt = '\n'.join(prompts)
    else:
        raise

Prevention

Chunk image lists to <=3 before calling run()
Enforce an image-attachment cap in UI/batch code
Treat run() as a single-few-image call, not a batch API
Iterate per image if independent prompts are needed

When it happens

Trigger: Calling run(images=[...]) with more than 3 PIL/torch images, e.g. batching a whole folder of images into one image-to-prompt request.

Common situations: Processing directories of images in a single call instead of iterating; a UI that accumulates attached images without capping; misreading run() as accepting batches.

Related errors

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/987339934f903d62. Report an issue: GitHub.