docling-project/docling · error · ValueError

Prompt list length ({len(prompt)}) must match image count ({

Error message

Prompt list length ({len(prompt)}) must match image count ({len(images)})

What it means

ApiVlmModel's raw-image path raises ValueError when a prompt list supplied for a batch of images does not have exactly one prompt per image. A plain string prompt is broadcast to all images; a list must match the image count element-for-element before any API call is made.

Source

Thrown at docling/models/vlm_pipeline_models/api_vlm_model.py:110

        # Yield pages preserving original order
        for page in original_order:
            yield page

    def process_images(
        self,
        image_batch: Iterable[Union[Image, np.ndarray]],
        prompt: Union[str, list[str]],
    ) -> Iterable[VlmPrediction]:
        """Process raw images without page metadata."""
        images = list(image_batch)

        # Handle prompt parameter
        if isinstance(prompt, str):
            prompts = [prompt] * len(images)
        elif isinstance(prompt, list):
            if len(prompt) != len(images):
                raise ValueError(
                    f"Prompt list length ({len(prompt)}) must match image count ({len(images)})"
                )
            prompts = prompt

        def _process_single_image(image_prompt_pair):
            image, prompt_text = image_prompt_pair

            # Convert numpy array to PIL Image if needed
            if isinstance(image, np.ndarray):
                if image.ndim == 3 and image.shape[2] in [3, 4]:
                    from PIL import Image as PILImage

                    image = PILImage.fromarray(image.astype(np.uint8))
                elif image.ndim == 2:
                    from PIL import Image as PILImage

                    image = PILImage.fromarray(image.astype(np.uint8), mode="L")
                else:

View on GitHub (pinned to 61d76f1ff3)

Solutions

Pass a single string prompt to reuse for every image
Regenerate the prompt list from the exact same list(image_batch) you pass in, or zip images and prompts together before calling
Add a length check in your own batching code and fail early with your own error message

Example fix

# before
images = [im for im in batch if im is not None]  # filtered
out = model._process_batch(images, prompts_for_full_batch)
# after
images = [im for im in batch if im is not None]
prompts = [prompts_for_full_batch[i] for i in kept_indices]
assert len(prompts) == len(images)
out = model._process_batch(images, prompts)

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

def is_matched_prompts(prompt: object, images: list) -> bool:
    if isinstance(prompt, str):
        return True
    return isinstance(prompt, list) and all(isinstance(p, str) for p in prompt) and len(prompt) == len(images)

Try / catch

try:
    preds = model._process_batch(images, prompts)
except ValueError as e:
    if 'must match image count' in str(e):
        preds = model._process_batch(images, shared_prompt_str)
    else:
        raise

Prevention

Build prompts with a list comprehension over the same images list you pass
Never cache prompt lists across re-batching steps
Log batch size and prompt count together when instrumenting

When it happens

Trigger: Calling _process_batch with prompt=['a','b'] but three images, or one image with two prompts. Common when zipping images and prompts that were sourced from different filtered collections.

Common situations: Prebuilding per-page prompts then re-chunking images into different batch sizes; mixing prompt-building logic that assumes one batch size with an image iterator that yields another.

Related errors

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