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

Raised by VlmConvertModel when processing a batch of images with a per-image prompt list whose length differs from the number of images in the batch. The model either broadcasts a single string prompt to all images, or requires exactly one prompt per image. A mismatched list is rejected before any inference runs.

Source

Thrown at docling/models/stages/vlm_convert/vlm_convert_model.py:273

        Yields:
            VLM predictions for each image

        Raises:
            ValueError: If prompt list length doesn't match image count
        """
        if not self.enabled:
            return

        images = list(image_batch)
        if not images:
            return

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

        # Process batch of images (shared generation template)
        engine_inputs = self._build_engine_inputs(images, prompts)

        # Run batch inference
        outputs = self.engine.predict_batch(engine_inputs)

        # Convert outputs to VlmPredictions
        for output in outputs:
            yield _prediction_from_engine_output(output)

    def __del__(self):
        """Cleanup engine resources."""
        if hasattr(self, "engine"):

View on GitHub (pinned to 61d76f1ff3)

Solutions

Pass a single string prompt so it is broadcast to every image in the batch
If per-image prompts are needed, rebuild the prompt list from the same iterable you pass as image_batch so lengths always match
Add an assert len(prompts) == len(images) right before the call while developing

Example fix

# before
prompts = [p.prompt for p in all_pages]  # built from unfiltered pages
results = model(image_batch=valid_images, prompt=prompts)  # ValueError if some pages dropped
# after
prompts = [p.prompt for p in pages_for_batch]
assert len(prompts) == len(valid_images)
results = model(image_batch=valid_images, prompt=prompts)

Defensive patterns

Strategy: validation

Validate before calling

images = list(image_batch)
if isinstance(prompt, list) and len(prompt) != len(images):
    raise ValueError(f"prompt count {len(prompt)} != image count {len(images)}")

Type guard

from typing import Union, Sequence

def is_valid_prompt_for_batch(prompt: Union[str, Sequence[str]], n_images: int) -> bool:
    return isinstance(prompt, str) or (isinstance(prompt, list) and len(prompt) == n_images)

Try / catch

try:
    results = model(images, prompts)
except ValueError as e:
    if 'must match image count' in str(e):
        results = model(images, prompts[0] if isinstance(prompts, list) and len(set(prompts)) == 1 else prompts[:len(images)])
    else:
        raise

Prevention

Always derive prompts and images from one zipped source iterable
Assert length equality in debug builds before every batch call
Prefer a single shared string prompt unless per-image text is truly required

When it happens

Trigger: Calling the VLM conversion model's batch entry point with prompt as a list (e.g. ['p1','p2']) while image_batch contains a different number of Image or np.ndarray items (e.g. 3 pages). Happens when page batching changes the batch size but prompts were built for a different page count.

Common situations: Building prompts per page index and then filtering/dropping pages (e.g. skipped failed pages) without filtering the prompt list; mixing a single shared prompt path and a per-page prompt path in a custom pipeline.

Related errors

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