{"record":{"id":"116d071f550e71f6","repo":"docling-project/docling","slug":"number-of-prompts-len-prompt-must-match-numbe-116d07","errorCode":null,"errorMessage":"Number of prompts ({len(prompt)}) must match number of images ({len(pil_images)})","messagePattern":"Number of prompts \\((.+?)\\) must match number of images \\((.+?)\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/vlm_pipeline_models/hf_transformers_model.py","lineNumber":281,"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 prompts (1 per image)\n        if isinstance(prompt, str):\n            user_prompts = [prompt] * len(pil_images)\n        else:\n            if len(prompt) != len(pil_images):\n                raise ValueError(\n                    f\"Number of prompts ({len(prompt)}) must match number of images ({len(pil_images)})\"\n                )\n            user_prompts = prompt\n\n        # Use your prompt formatter verbatim\n        if self.vlm_options.transformers_prompt_style == TransformersPromptStyle.NONE:\n            inputs = self.processor(\n                pil_images,\n                return_tensors=\"pt\",\n                padding=True,  # pad across batch for both text and vision\n                **self.vlm_options.extra_processor_kwargs,\n            )\n        else:\n            prompts: list[str] = [self.formulate_prompt(p) for p in user_prompts]\n\n            # -- Processor performs BOTH text+image preprocessing + batch padding (recommended)\n            inputs = self.processor(\n                text=prompts,","sourceCodeStart":263,"sourceCodeEnd":299,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/vlm_pipeline_models/hf_transformers_model.py#L263-L299","documentation":"The Transformers VLM path requires exactly one user prompt per PIL image in the batch. A single string is broadcast; a list must satisfy len(prompt) == len(pil_images), otherwise ValueError is raised before the processor is invoked.","triggerScenarios":"Calling the model with a per-page prompt list built from a different page set than the image batch; converting one document where images were deduplicated but prompts were not (or vice versa).","commonSituations":"Custom chunking that re-batches images after prompts were generated; conditionally dropping blank pages from images while keeping all prompts; off-by-one when slicing pages.","solutions":["Use one shared string prompt when all images should get the same instruction","Build prompts by iterating the same image list: [make_prompt(im) for im in images]","Assert equality of both lengths at the call site in dev builds"],"exampleFix":"# before\nprompts = [f\"OCR page {i}\" for i in range(total_pages)]\nmodel(batch_of_10_images, prompts)  # total_pages != 10 -> ValueError\n# after\nprompts = [f\"OCR page {p.page_no}\" for p in batch_pages]\nassert len(prompts) == len(batch_images)\nmodel(batch_images, prompts)","handlingStrategy":"validation","validationCode":"pil_images = list(images)\nif isinstance(prompt, list):\n    if len(prompt) != len(pil_images):\n        prompt = [prompt[i] if i < len(prompt) else default_prompt for i in range(len(pil_images))]  # or fail fast","typeGuard":"def prompts_match(prompt: object, n: int) -> bool:\n    return isinstance(prompt, str) or (isinstance(prompt, list) and len(prompt) == n)","tryCatchPattern":"try:\n    model(batch, prompts)\nexcept ValueError as e:\n    if 'must match number of images' in str(e):\n        model(batch, shared_prompt)\n    else:\n        raise","preventionTips":["Generate prompts in the same loop that assembles the image batch","Wrap the call in a small helper that enforces the invariant once","Log both counts whenever a mismatch error path is hit"],"tags":["prompt","batching","validation","transformers"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}