{"record":{"id":"8a6086cd6167b779","repo":"docling-project/docling","slug":"prompt-list-length-len-prompt-must-match-imag-8a6086","errorCode":null,"errorMessage":"Prompt list length ({len(prompt)}) must match image count ({len(images)})","messagePattern":"Prompt list length \\((.+?)\\) must match image count \\((.+?)\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/vlm_pipeline_models/api_vlm_model.py","lineNumber":110,"sourceCode":"\n        # Yield pages preserving original order\n        for page in original_order:\n            yield page\n\n    def process_images(\n        self,\n        image_batch: Iterable[Union[Image, np.ndarray]],\n        prompt: Union[str, list[str]],\n    ) -> Iterable[VlmPrediction]:\n        \"\"\"Process raw images without page metadata.\"\"\"\n        images = list(image_batch)\n\n        # Handle prompt parameter\n        if isinstance(prompt, str):\n            prompts = [prompt] * len(images)\n        elif isinstance(prompt, list):\n            if len(prompt) != len(images):\n                raise ValueError(\n                    f\"Prompt list length ({len(prompt)}) must match image count ({len(images)})\"\n                )\n            prompts = prompt\n\n        def _process_single_image(image_prompt_pair):\n            image, prompt_text = image_prompt_pair\n\n            # Convert numpy array to PIL Image if needed\n            if isinstance(image, np.ndarray):\n                if image.ndim == 3 and image.shape[2] in [3, 4]:\n                    from PIL import Image as PILImage\n\n                    image = PILImage.fromarray(image.astype(np.uint8))\n                elif image.ndim == 2:\n                    from PIL import Image as PILImage\n\n                    image = PILImage.fromarray(image.astype(np.uint8), mode=\"L\")\n                else:","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/vlm_pipeline_models/api_vlm_model.py#L92-L128","documentation":"ApiVlmModel's raw-image path raises ValueError when a prompt list supplied for a batch of images does not have exactly one prompt per image. A plain string prompt is broadcast to all images; a list must match the image count element-for-element before any API call is made.","triggerScenarios":"Calling _process_batch with prompt=['a','b'] but three images, or one image with two prompts. Common when zipping images and prompts that were sourced from different filtered collections.","commonSituations":"Prebuilding per-page prompts then re-chunking images into different batch sizes; mixing prompt-building logic that assumes one batch size with an image iterator that yields another.","solutions":["Pass a single string prompt to reuse for every image","Regenerate the prompt list from the exact same list(image_batch) you pass in, or zip images and prompts together before calling","Add a length check in your own batching code and fail early with your own error message"],"exampleFix":"# before\nimages = [im for im in batch if im is not None]  # filtered\nout = model._process_batch(images, prompts_for_full_batch)\n# after\nimages = [im for im in batch if im is not None]\nprompts = [prompts_for_full_batch[i] for i in kept_indices]\nassert len(prompts) == len(images)\nout = model._process_batch(images, prompts)","handlingStrategy":"validation","validationCode":"images = list(image_batch)\nif isinstance(prompt, list):\n    assert len(prompt) == len(images), f'{len(prompt)} prompts vs {len(images)} images'","typeGuard":"def is_matched_prompts(prompt: object, images: list) -> bool:\n    if isinstance(prompt, str):\n        return True\n    return isinstance(prompt, list) and all(isinstance(p, str) for p in prompt) and len(prompt) == len(images)","tryCatchPattern":"try:\n    preds = model._process_batch(images, prompts)\nexcept ValueError as e:\n    if 'must match image count' in str(e):\n        preds = model._process_batch(images, shared_prompt_str)\n    else:\n        raise","preventionTips":["Build prompts with a list comprehension over the same images list you pass","Never cache prompt lists across re-batching steps","Log batch size and prompt count together when instrumenting"],"tags":["vlm","api","prompt","batching","validation"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}