{"record":{"id":"f83b953caa545214","repo":"docling-project/docling","slug":"prompt-list-length-len-prompt-must-match-imag","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/stages/vlm_convert/vlm_convert_model.py","lineNumber":273,"sourceCode":"        Yields:\n            VLM predictions for each image\n\n        Raises:\n            ValueError: If prompt list length doesn't match image count\n        \"\"\"\n        if not self.enabled:\n            return\n\n        images = list(image_batch)\n        if not images:\n            return\n\n        # Handle prompt\n        if isinstance(prompt, str):\n            prompts = [prompt] * len(images)\n        else:\n            if len(prompt) != len(images):\n                raise ValueError(\n                    f\"Prompt list length ({len(prompt)}) must match \"\n                    f\"image count ({len(images)})\"\n                )\n            prompts = prompt\n\n        # Process batch of images (shared generation template)\n        engine_inputs = self._build_engine_inputs(images, prompts)\n\n        # Run batch inference\n        outputs = self.engine.predict_batch(engine_inputs)\n\n        # Convert outputs to VlmPredictions\n        for output in outputs:\n            yield _prediction_from_engine_output(output)\n\n    def __del__(self):\n        \"\"\"Cleanup engine resources.\"\"\"\n        if hasattr(self, \"engine\"):","sourceCodeStart":255,"sourceCodeEnd":291,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/stages/vlm_convert/vlm_convert_model.py#L255-L291","documentation":"Raised by VlmConvertModel when processing a batch of images with a per-image prompt list whose length differs from the number of images in the batch. The model either broadcasts a single string prompt to all images, or requires exactly one prompt per image. A mismatched list is rejected before any inference runs.","triggerScenarios":"Calling the VLM conversion model's batch entry point with prompt as a list (e.g. ['p1','p2']) while image_batch contains a different number of Image or np.ndarray items (e.g. 3 pages). Happens when page batching changes the batch size but prompts were built for a different page count.","commonSituations":"Building prompts per page index and then filtering/dropping pages (e.g. skipped failed pages) without filtering the prompt list; mixing a single shared prompt path and a per-page prompt path in a custom pipeline.","solutions":["Pass a single string prompt so it is broadcast to every image in the batch","If per-image prompts are needed, rebuild the prompt list from the same iterable you pass as image_batch so lengths always match","Add an assert len(prompts) == len(images) right before the call while developing"],"exampleFix":"# before\nprompts = [p.prompt for p in all_pages]  # built from unfiltered pages\nresults = model(image_batch=valid_images, prompt=prompts)  # ValueError if some pages dropped\n# after\nprompts = [p.prompt for p in pages_for_batch]\nassert len(prompts) == len(valid_images)\nresults = model(image_batch=valid_images, prompt=prompts)","handlingStrategy":"validation","validationCode":"images = list(image_batch)\nif isinstance(prompt, list) and len(prompt) != len(images):\n    raise ValueError(f\"prompt count {len(prompt)} != image count {len(images)}\")","typeGuard":"from typing import Union, Sequence\n\ndef is_valid_prompt_for_batch(prompt: Union[str, Sequence[str]], n_images: int) -> bool:\n    return isinstance(prompt, str) or (isinstance(prompt, list) and len(prompt) == n_images)","tryCatchPattern":"try:\n    results = model(images, prompts)\nexcept ValueError as e:\n    if 'must match image count' in str(e):\n        results = model(images, prompts[0] if isinstance(prompts, list) and len(set(prompts)) == 1 else prompts[:len(images)])\n    else:\n        raise","preventionTips":["Always derive prompts and images from one zipped source iterable","Assert length equality in debug builds before every batch call","Prefer a single shared string prompt unless per-image text is truly required"],"tags":["vlm","prompt","batching","validation"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}