{"record":{"id":"fa15266f4020d5d6","repo":"docling-project/docling","slug":"examples-batch-length-must-match-messages-batch-le","errorCode":null,"errorMessage":"Examples batch length must match messages batch length","messagePattern":"Examples batch length must match messages batch length","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/extraction/nuextract_transformers_model.py","lineNumber":91,"sourceCode":"    messages_batch = messages if is_batch else [messages]\n    is_batch_examples = (\n        examples\n        and isinstance(examples, list)\n        and (isinstance(examples[0], list) or examples[0] is None)\n    )\n    examples_batch = (\n        examples\n        if is_batch_examples\n        else ([examples] if examples is not None else None)\n    )\n\n    # Ensure examples batch matches messages batch if provided\n    if examples and len(examples_batch) != len(messages_batch):\n        if not is_batch and len(examples_batch) == 1:\n            # Single example set for a single input is fine\n            pass\n        else:\n            raise ValueError(\"Examples batch length must match messages batch length\")\n\n    # Process all inputs, maintaining correct order\n    all_images = []\n    for i, message_group in enumerate(messages_batch):\n        # Get example images for this input\n        if examples and i < len(examples_batch):\n            input_example_images = extract_example_images(examples_batch[i])\n            all_images.extend(input_example_images)\n\n        # Get message images for this input\n        input_message_images = process_vision_info(message_group)[0] or []\n        all_images.extend(input_message_images)\n\n    return all_images if all_images else None\n\n\nclass NuExtractTransformersModel(BaseVlmModel, HuggingFaceModelDownloadMixin):\n    def __init__(","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/extraction/nuextract_transformers_model.py#L73-L109","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Make len(examples) == len(messages) when passing batched inputs: one example group per message group.","For a single input, pass a single example (or None) rather than a list of a different size.","Broadcast explicitly: examples = [shared_example] * len(messages) if the same examples apply to every input."],"exampleFix":"# before\nmessages = [msg_page1, msg_page2, msg_page3]\nexamples = [ex_a, ex_b]  # length 2 vs 3 -> ValueError\n\n# after\nshared = [ex_a, ex_b]\nexamples = [shared] * len(messages)  # one example group per message group","handlingStrategy":"validation","validationCode":"if examples is not None and is_batch_messages:\n    assert len(examples) == len(messages), 'examples batch must match messages batch'","typeGuard":null,"tryCatchPattern":"try:\n    images = collect_images(messages, examples)\nexcept ValueError as e:\n    if 'batch length must match' in str(e):\n        examples = [examples[0]] * len(messages)  # broadcast shared example set\n        images = collect_images(messages, examples)","preventionTips":["Build examples and messages in one loop so their lengths stay in lockstep.","Broadcast explicitly ([shared] * len(messages)) instead of relying on single-input exemptions."],"tags":["nuextract","batching","validation","extraction"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}