docling-project/docling · error · ValueError

Number of templates ({len(prompt)}) must match number of ima

Error message

Number of templates ({len(prompt)}) must match number of images ({len(pil_images)})

What it means

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.

Source

Thrown at docling/models/extraction/nuextract_transformers_model.py:209

                elif img.ndim == 2:
                    pil_img = PILImage.fromarray(img.astype(np.uint8), mode="L")
                else:
                    raise ValueError(f"Unsupported numpy array shape: {img.shape}")
            else:
                pil_img = img
            if pil_img.mode != "RGB":
                pil_img = pil_img.convert("RGB")
            pil_images.append(pil_img)

        if not pil_images:
            return

        # Normalize templates (1 per image)
        if isinstance(prompt, str):
            templates = [prompt] * len(pil_images)
        else:
            if len(prompt) != len(pil_images):
                raise ValueError(
                    f"Number of templates ({len(prompt)}) must match number of images ({len(pil_images)})"
                )
            templates = prompt

        # Construct NuExtract input format
        inputs = []
        for pil_img, template in zip(pil_images, templates):
            input_item = {
                "document": {"type": "image", "image": pil_img},
                "template": template,
            }
            inputs.append(input_item)

        # Create messages structure for batch processing
        messages = [
            [
                {
                    "role": "user",

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Pass a single template string when every image should use the same template; it is broadcast automatically.
2. Otherwise ensure len(prompt) == number of images (zip them in pairs upstream to keep them aligned).
3. Build inputs as (image, template) pairs first, then split into two aligned lists at call time.

Example fix

# before
out = model(images_10pages, prompt=templates_9)  # lengths differ

# after
pairs = [(img, tpl) for img, tpl in zip(images, templates) if tpl]
imgs, tpls = zip(*pairs)
out = model(list(imgs), prompt=list(tpls))

if isinstance(prompt, list):
    assert len(prompt) == len(image_batch), f'{len(prompt)} templates vs {len(image_batch)} images'
else:
    prompt = [prompt] * len(image_batch)  # or keep the string for broadcasting

try:
    preds = model(image_batch, prompt)
except ValueError as e:
    if 'must match number of images' in str(e):
        template = prompt[0] if isinstance(prompt, list) else prompt
        preds = model(image_batch, template)  # broadcast single template

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Examples batch length must match messages batch length
• Examples batch length must match messages batch length
• Number of prompts ({len(prompt)}) must match number of image
• qwen-vl-utils is required for NuExtractTransformersModel. Pl
• Unsupported numpy array shape: {img.shape}

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/2ee9dd6779d6bbf8. Report an issue: GitHub.