docling-project/docling · error · ValueError

prompt must be str or list[str], got {type(prompt)}

Error message

prompt must be str or list[str], got {type(prompt)}

What it means

The prompt parameter of the vLLM VLM generation API accepts only str (broadcast to all images) or list (one prompt per image). Any other type — int, dict, tuple, a generator, an ndarray — fails this isinstance check and raises ValueError with the offending type. This is the API's input contract enforcement before any formatting happens.

Source

Thrown at docling/models/vlm_pipeline_models/vllm_model.py:307

                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 prompts
        if isinstance(prompt, str):
            user_prompts = [prompt] * len(pil_images)
        elif isinstance(prompt, list):
            if len(prompt) != len(pil_images):
                raise ValueError(
                    f"Number of prompts ({len(prompt)}) must match number of images ({len(pil_images)})"
                )
            user_prompts = prompt
        else:
            raise ValueError(f"prompt must be str or list[str], got {type(prompt)}")

        # Format prompts
        prompts: list[str] = [self.formulate_prompt(up) for up in user_prompts]

        # Build vLLM inputs
        llm_inputs = [
            {"prompt": p, "multi_modal_data": {"image": im}}
            for p, im in zip(prompts, pil_images)
        ]

        # Generate
        assert self.llm is not None and self.sampling_params is not None
        start_time = time.time()
        outputs = self.llm.generate(llm_inputs, sampling_params=self.sampling_params)  # type: ignore
        generation_time = time.time() - start_time

        # Optional debug
        if outputs:

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Pass a plain Python str for a shared prompt, or list[str] matched to the image count
2. Convert chat-style messages to a single string first: prompt = '\n'.join(m['content'] for m in messages)
3. Materialize generators: prompt = list(prompt_gen)

Example fix

# before
model.generate(images, prompt={'role': 'user', 'content': 'describe'})

# after
model.generate(images, prompt='describe')

if not isinstance(prompt, (str, list)) or (isinstance(prompt, list) and not all(isinstance(p, str) for p in prompt)):
    raise TypeError(f'prompt must be str or list[str], got {type(prompt).__name__}')

def is_valid_prompt(p) -> bool:
    return isinstance(p, str) or (isinstance(p, list) and all(isinstance(x, str) for x in p))

When it happens

Trigger: Calling generate(images, prompt=0), prompt=('describe',), prompt=iter([...]), prompt={'role': 'user', ...} (chat-format dict), or a numpy array of strings — anything that is neither str nor list.

Common situations: Porting code from another SDK that accepts OpenAI-style message dicts or tuples; passing a generator expression; config-driven prompt values parsed from YAML as a non-string scalar (e.g. `prompt: 1`).

Related errors

• Number of prompts ({len(prompt)}) must match number of image
• Expected VllmVlmEngineOptions, got {type(options)}
• {repo_id} is supported by the Transformers engine only with
• vLLM is not installed. Please install it via `pip install vl
• vLLM is not installed. It is not yet available on Python 3.1

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