{"record":{"id":"80b89f5f7a9f5662","repo":"docling-project/docling","slug":"examples-batch-length-must-match-messages-batch-le-80b89f","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/prompt_utils.py","lineNumber":149,"sourceCode":"    is_batch = messages and isinstance(messages[0], list)\n    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    if examples and examples_batch is not None:\n        if len(examples_batch) != len(messages_batch):\n            if not is_batch and len(examples_batch) == 1:\n                pass\n            else:\n                raise ValueError(\n                    \"Examples batch length must match messages batch length\"\n                )\n\n    all_images = []\n    for i, message_group in enumerate(messages_batch):\n        if examples and examples_batch is not None and i < len(examples_batch):\n            all_images.extend(extract_example_images(examples_batch[i]))\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","sourceCodeStart":131,"sourceCodeEnd":161,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/extraction/prompt_utils.py#L131-L161","documentation":"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.","triggerScenarios":"Calling the helper with is_batch inputs where len(examples_batch) != len(messages_batch) and the single/single case does not apply.","commonSituations":"Reusing example sets computed for a different page count after filtering drops pages; asymmetric batching between examples and messages in a custom extraction loop.","solutions":["Align lengths: build one example group per message group before calling the helper.","Broadcast a shared example set: examples = [shared] * len(messages).","Omit examples entirely (pass None) when they are not needed for every input."],"exampleFix":"# before\nmessages = build_batch(pages)          # 5 groups\nexamples = load_examples('train.json')[:3]  # 3 groups -> ValueError\n\n# after\nshared = load_examples('train.json')[:3]\nexamples = [shared] * len(messages)    # 5 groups, aligned","handlingStrategy":"validation","validationCode":"if examples is not None:\n    n = len(examples) if is_batch_examples else 1\n    m = len(messages) if is_batch_messages else 1\n    assert n == m or (not is_batch_messages and n == 1), 'examples/messages batch length mismatch'","typeGuard":null,"tryCatchPattern":"try:\n    images = collect_vision_images(messages, examples)\nexcept ValueError as e:\n    if 'batch length must match' in str(e):\n        examples = [examples] * len(messages)\n        images = collect_vision_images(messages, examples)","preventionTips":["Derive examples and messages from the same page/document list in one pass.","Broadcast a shared example set explicitly when all inputs use the same examples."],"tags":["extraction","batching","validation","examples"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}