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

Thrown by TransformersExtractionModel.process_images when the caller passes a list of prompts whose length differs from the number of images produced from the batch. A single string prompt is broadcast to all images, but a list must be one-to-one with the image batch. The error surfaces before any tokenization or model inference happens.

Source

Thrown at docling/models/extraction/transformers_extraction_model.py:143

                    pil_img = PILImage.fromarray(img.astype(np.uint8))
                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

        if isinstance(prompt, str):
            templates = [prompt] * len(pil_images)
        else:
            if len(prompt) != len(pil_images):
                raise ValueError(
                    f"Number of prompts ({len(prompt)}) must match "
                    f"number of images ({len(pil_images)})"
                )
            templates = prompt

        # Build tokenized inputs based on prompt style
        if self.prompt_style == ExtractionPromptStyle.NUEXTRACT:
            processor_inputs = build_nuextract_inputs(
                processor=self.processor,
                images=pil_images,
                templates=templates,
                device=self.device,
                extra_processor_kwargs=self.vlm_options.extra_processor_kwargs,
            )
        else:
            processor_inputs = build_granite_vision_inputs(
                processor=self.processor,
                images=pil_images,

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. If all images should use the same prompt, pass a plain string instead of a list (it is broadcast automatically).
2. Otherwise assert len(prompts) == len(images) before the call and fix the construction of the prompt list (usually a zip/filter mismatch upstream).
3. Build prompts and images together in one pass (e.g. zip(images, prompts)) so they cannot diverge.

Example fix

# before
prompts = [TEMPLATE] * 5
results = model.process_images(images[:4], prompts)  # 5 prompts, 4 images

# after
results = model.process_images(images, TEMPLATE)  # broadcast one string to all images

# or, per-image prompts:
assert len(prompts) == len(images)
results = model.process_images(images, prompts)

if isinstance(prompts, list):
    assert len(prompts) == len(list(image_batch)), (
        f'{len(prompts)} prompts vs {len(image_batch)} images'
    )

from typing import Union, List
from docling.datamodel.base_settings import Image

def is_valid_prompt(prompt: Union[str, List[str]], n_images: int) -> bool:
    return isinstance(prompt, str) or len(prompt) == n_images

try:
    results = model.process_images(images, prompts)
except ValueError as e:
    if 'must match' in str(e):
        results = model.process_images(images, prompts[:len(images)])  # or fix upstream
    else:
        raise

When it happens

Trigger: Calling process_images(image_batch, prompt=[...]) with len(prompt) != number of valid images in image_batch. Note that a batch containing zero valid images returns early, so the mismatch only occurs with >=1 image; also numpy arrays that are not 2D or 3D-with-3/4-channels raise a different error first.

Common situations: Building per-image templates for NuExtract-style extraction (each image needs its own schema template) and dropping or adding one entry; filtering images out of a batch but forgetting to filter the matching prompt; off-by-one slicing of prompts.

Related errors

• Examples batch length must match messages batch length
• Number of templates ({len(prompt)}) must match number of ima
• Examples batch length must match messages batch length
• KServe v2 output batch size mismatch for labels: expected {l
• Prompt list length ({len(prompt)}) must match image count ({

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