{"record":{"id":"09ac07deedf30973","repo":"docling-project/docling","slug":"number-of-prompts-len-prompt-must-match-numbe-09ac07","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":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/vlm_pipeline_models/vllm_model.py","lineNumber":302,"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\n        if isinstance(prompt, str):\n            user_prompts = [prompt] * len(pil_images)\n        elif isinstance(prompt, list):\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        else:\n            raise ValueError(f\"prompt must be str or list[str], got {type(prompt)}\")\n\n        # Format prompts\n        prompts: list[str] = [self.formulate_prompt(up) for up in user_prompts]\n\n        # Build vLLM inputs\n        llm_inputs = [\n            {\"prompt\": p, \"multi_modal_data\": {\"image\": im}}\n            for p, im in zip(prompts, pil_images)\n        ]\n\n        # Generate\n        assert self.llm is not None and self.sampling_params is not None\n        start_time = time.time()","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/vlm_pipeline_models/vllm_model.py#L284-L320","documentation":"When the prompt argument to the vLLM VLM generation call is a list, its length must exactly equal the number of normalized PIL images, because prompts and images are zipped one-to-one into vLLM inputs. A length mismatch means some images would get no prompt or prompts would be dropped, so the code raises ValueError before building inputs.","triggerScenarios":"Calling generate(image_batch=[img1, img2], prompt=['p1']) or any list-prompt call where len(prompt) != len(image_batch). Also occurs when one image normalizes into a different count than expected (e.g. an empty batch returns early, or a caller builds prompts from a stale batch size).","commonSituations":"Dynamic batches where images are filtered (blank pages dropped) but the prompt list is built from the unfiltered count; reusing a prompt list across batches of different sizes; prompt built per-page while images come from a page range subset.","solutions":["Pass a single str prompt when every image should use the same prompt — it is automatically broadcast to all images","Build the prompt list from the exact same list comprehension/filter that produced the images: prompts = [make_prompt(p) for p in pages]; images = [p.image for p in pages]","Add an explicit assert len(prompts) == len(images) before the call to fail at the source of the mismatch"],"exampleFix":"# before\nprompts = [prompt_for_page(p) for p in all_pages]\nmodel.generate(selected_images, prompts)  # lengths differ\n\n# after\nselected = [p for p in all_pages if p.keep]\nmodel.generate([p.image for p in selected], [prompt_for_page(p) for p in selected])","handlingStrategy":"validation","validationCode":"assert isinstance(prompt, str) or len(prompt) == len(image_batch), (\n    f'prompts={len(prompt)} images={len(image_batch)}')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Derive prompts and images from the same list/comprehension so they cannot diverge","Use a single str prompt whenever all images share the same instruction","Add an assert on lengths right where the batch is assembled"],"tags":["vlm","vllm","prompt","batching"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}