docling-project/docling · error · ValueError

Number of prompts ({len(prompt)}) must match number of image

Error message

Number of prompts ({len(prompt)}) must match number of images ({len(pil_images)})

What it means

When the prompt argument to the vLLM VLM generation call is a list, its length must exactly equal the number of normalized PIL images, because prompts and images are zipped one-to-one into vLLM inputs. A length mismatch means some images would get no prompt or prompts would be dropped, so the code raises ValueError before building inputs.

Source

Thrown at docling/models/vlm_pipeline_models/vllm_model.py:302

                elif img.ndim == 2:
                    pil_img = PILImage.fromarray(img.astype(np.uint8), mode="L")
                else:
                    raise ValueError(f"Unsupported numpy array shape: {img.shape}")
            else:
                pil_img = img
            if pil_img.mode != "RGB":
                pil_img = pil_img.convert("RGB")
            pil_images.append(pil_img)

        if not pil_images:
            return

        # Normalize prompts
        if isinstance(prompt, str):
            user_prompts = [prompt] * len(pil_images)
        elif isinstance(prompt, list):
            if len(prompt) != len(pil_images):
                raise ValueError(
                    f"Number of prompts ({len(prompt)}) must match number of images ({len(pil_images)})"
                )
            user_prompts = prompt
        else:
            raise ValueError(f"prompt must be str or list[str], got {type(prompt)}")

        # Format prompts
        prompts: list[str] = [self.formulate_prompt(up) for up in user_prompts]

        # Build vLLM inputs
        llm_inputs = [
            {"prompt": p, "multi_modal_data": {"image": im}}
            for p, im in zip(prompts, pil_images)
        ]

        # Generate
        assert self.llm is not None and self.sampling_params is not None
        start_time = time.time()

View on GitHub (pinned to 61d76f1ff3)

Solutions

Pass a single str prompt when every image should use the same prompt — it is automatically broadcast to all images
Build the prompt list from the exact same list comprehension/filter that produced the images: prompts = [make_prompt(p) for p in pages]; images = [p.image for p in pages]
Add an explicit assert len(prompts) == len(images) before the call to fail at the source of the mismatch

Example fix

# before
prompts = [prompt_for_page(p) for p in all_pages]
model.generate(selected_images, prompts)  # lengths differ

# after
selected = [p for p in all_pages if p.keep]
model.generate([p.image for p in selected], [prompt_for_page(p) for p in selected])

Defensive patterns

Strategy: validation

Validate before calling

assert isinstance(prompt, str) or len(prompt) == len(image_batch), (
    f'prompts={len(prompt)} images={len(image_batch)}')

Prevention

Derive prompts and images from the same list/comprehension so they cannot diverge
Use a single str prompt whenever all images share the same instruction
Add an assert on lengths right where the batch is assembled

When it happens

Trigger: Calling generate(image_batch=[img1, img2], prompt=['p1']) or any list-prompt call where len(prompt) != len(image_batch). Also occurs when one image normalizes into a different count than expected (e.g. an empty batch returns early, or a caller builds prompts from a stale batch size).

Common situations: Dynamic batches where images are filtered (blank pages dropped) but the prompt list is built from the unfiltered count; reusing a prompt list across batches of different sizes; prompt built per-page while images come from a page range subset.

Related errors

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/09ac07deedf30973. Report an issue: GitHub.