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 NuExtract image-collection helper: when few-shot examples are supplied alongside a batch of messages, the number of example groups must equal the number of message groups. A single example set applied to a single input is allowed, but mismatched batch lengths are rejected before images are gathered.

Source

Thrown at docling/models/extraction/nuextract_transformers_model.py:91

    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)
    )

    # Ensure examples batch matches messages batch if provided
    if examples and len(examples_batch) != len(messages_batch):
        if not is_batch and len(examples_batch) == 1:
            # Single example set for a single input is fine
            pass
        else:
            raise ValueError("Examples batch length must match messages batch length")

    # Process all inputs, maintaining correct order
    all_images = []
    for i, message_group in enumerate(messages_batch):
        # Get example images for this input
        if examples and i < len(examples_batch):
            input_example_images = extract_example_images(examples_batch[i])
            all_images.extend(input_example_images)

        # Get message images for this input
        input_message_images = process_vision_info(message_group)[0] or []
        all_images.extend(input_message_images)

    return all_images if all_images else None


class NuExtractTransformersModel(BaseVlmModel, HuggingFaceModelDownloadMixin):
    def __init__(

View on GitHub (pinned to 61d76f1ff3)

Solutions

  1. Make len(examples) == len(messages) when passing batched inputs: one example group per message group.
  2. For a single input, pass a single example (or None) rather than a list of a different size.
  3. Broadcast explicitly: examples = [shared_example] * len(messages) if the same examples apply to every input.

Example fix

# before
messages = [msg_page1, msg_page2, msg_page3]
examples = [ex_a, ex_b]  # length 2 vs 3 -> ValueError

# after
shared = [ex_a, ex_b]
examples = [shared] * len(messages)  # one example group per message group
Defensive patterns

Strategy: validation

Validate before calling

if examples is not None and is_batch_messages:
    assert len(examples) == len(messages), 'examples batch must match messages batch'

Try / catch

try:
    images = collect_images(messages, examples)
except ValueError as e:
    if 'batch length must match' in str(e):
        examples = [examples[0]] * len(messages)  # broadcast shared example set
        images = collect_images(messages, examples)

Prevention

When it happens

Trigger: Calling the helper with messages as a batch (list of message lists) and examples of a different length (N examples vs M messages with N != M), where the single/single exemption does not apply.

Common situations: Prompting a whole page batch with one shared example list, or building examples per page but dropping one page from filtering; dynamic batches where examples were computed against a different length.

Related errors

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