docling-project/docling · error · ValueError

Examples batch length must match messages batch length

Error message

Examples batch length must match messages batch length

What it means

ValueError from the shared vision-input helper in prompt_utils: when examples are provided for a batched set of messages, the examples batch length must equal the messages batch length. The only exemption is a single non-batch input with a single example set; every other mismatch aborts image collection.

Source

Thrown at docling/models/extraction/prompt_utils.py:149

    is_batch = messages and isinstance(messages[0], list)
    messages_batch = messages if is_batch else [messages]
    is_batch_examples = (
        examples
        and isinstance(examples, list)
        and (isinstance(examples[0], list) or examples[0] is None)
    )
    examples_batch = (
        examples
        if is_batch_examples
        else ([examples] if examples is not None else None)
    )

    if examples and examples_batch is not None:
        if len(examples_batch) != len(messages_batch):
            if not is_batch and len(examples_batch) == 1:
                pass
            else:
                raise ValueError(
                    "Examples batch length must match messages batch length"
                )

    all_images = []
    for i, message_group in enumerate(messages_batch):
        if examples and examples_batch is not None and i < len(examples_batch):
            all_images.extend(extract_example_images(examples_batch[i]))
        input_message_images = process_vision_info(message_group)[0] or []
        all_images.extend(input_message_images)

    return all_images if all_images else None

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Align lengths: build one example group per message group before calling the helper.
2. Broadcast a shared example set: examples = [shared] * len(messages).
3. Omit examples entirely (pass None) when they are not needed for every input.

Example fix

# before
messages = build_batch(pages)          # 5 groups
examples = load_examples('train.json')[:3]  # 3 groups -> ValueError

# after
shared = load_examples('train.json')[:3]
examples = [shared] * len(messages)    # 5 groups, aligned

if examples is not None:
    n = len(examples) if is_batch_examples else 1
    m = len(messages) if is_batch_messages else 1
    assert n == m or (not is_batch_messages and n == 1), 'examples/messages batch length mismatch'

try:
    images = collect_vision_images(messages, examples)
except ValueError as e:
    if 'batch length must match' in str(e):
        examples = [examples] * len(messages)
        images = collect_vision_images(messages, examples)

When it happens

Trigger: Calling the helper with is_batch inputs where len(examples_batch) != len(messages_batch) and the single/single case does not apply.

Common situations: Reusing example sets computed for a different page count after filtering drops pages; asymmetric batching between examples and messages in a custom extraction loop.

Related errors

• Examples batch length must match messages batch length
• Number of templates ({len(prompt)}) must match number of ima
• Number of prompts ({len(prompt)}) must match number of image
• 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/80b89f5f7a9f5662. Report an issue: GitHub.