{"record":{"id":"2ee9dd6779d6bbf8","repo":"docling-project/docling","slug":"number-of-templates-len-prompt-must-match-num","errorCode":null,"errorMessage":"Number of templates ({len(prompt)}) must match number of images ({len(pil_images)})","messagePattern":"Number of templates \\((.+?)\\) must match number of images \\((.+?)\\)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/extraction/nuextract_transformers_model.py","lineNumber":209,"sourceCode":"                elif img.ndim == 2:\n                    pil_img = PILImage.fromarray(img.astype(np.uint8), mode=\"L\")\n                else:\n                    raise ValueError(f\"Unsupported numpy array shape: {img.shape}\")\n            else:\n                pil_img = img\n            if pil_img.mode != \"RGB\":\n                pil_img = pil_img.convert(\"RGB\")\n            pil_images.append(pil_img)\n\n        if not pil_images:\n            return\n\n        # Normalize templates (1 per image)\n        if isinstance(prompt, str):\n            templates = [prompt] * len(pil_images)\n        else:\n            if len(prompt) != len(pil_images):\n                raise ValueError(\n                    f\"Number of templates ({len(prompt)}) must match number of images ({len(pil_images)})\"\n                )\n            templates = prompt\n\n        # Construct NuExtract input format\n        inputs = []\n        for pil_img, template in zip(pil_images, templates):\n            input_item = {\n                \"document\": {\"type\": \"image\", \"image\": pil_img},\n                \"template\": template,\n            }\n            inputs.append(input_item)\n\n        # Create messages structure for batch processing\n        messages = [\n            [\n                {\n                    \"role\": \"user\",","sourceCodeStart":191,"sourceCodeEnd":227,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/extraction/nuextract_transformers_model.py#L191-L227","documentation":"ValueError from template normalization in NuExtractTransformersModel: when the prompt is a list of templates (not a single string), its length must equal the number of images, because each NuExtract input pairs exactly one document image with one extraction template.","triggerScenarios":"Calling the model with prompt as a list whose length differs from len(pil_images); e.g. page images batched to N while only N-1 templates were produced by an upstream filter.","commonSituations":"Dynamic batching where images are chunked by a different batch size than templates; a template skipped for one page (empty template) making the lists drift; mixing per-page templates with a multi-image batch call.","solutions":["Pass a single template string when every image should use the same template; it is broadcast automatically.","Otherwise ensure len(prompt) == number of images (zip them in pairs upstream to keep them aligned).","Build inputs as (image, template) pairs first, then split into two aligned lists at call time."],"exampleFix":"# before\nout = model(images_10pages, prompt=templates_9)  # lengths differ\n\n# after\npairs = [(img, tpl) for img, tpl in zip(images, templates) if tpl]\nimgs, tpls = zip(*pairs)\nout = model(list(imgs), prompt=list(tpls))","handlingStrategy":"validation","validationCode":"if isinstance(prompt, list):\n    assert len(prompt) == len(image_batch), f'{len(prompt)} templates vs {len(image_batch)} images'\nelse:\n    prompt = [prompt] * len(image_batch)  # or keep the string for broadcasting","typeGuard":null,"tryCatchPattern":"try:\n    preds = model(image_batch, prompt)\nexcept ValueError as e:\n    if 'must match number of images' in str(e):\n        template = prompt[0] if isinstance(prompt, list) else prompt\n        preds = model(image_batch, template)  # broadcast single template","preventionTips":["Carry (image, template) pairs through your pipeline and unzip only at the call boundary.","Use a single template string when all images share the same extraction schema."],"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"}