run-llama/llama_index · error · ValueError

Must provide either prompt or prompt_template_str.

Error message

Must provide either prompt or prompt_template_str.

What it means

The multimodal program factory mirrors LLMTextCompletionProgram: it needs exactly one prompt source. This instance fires when both prompt and prompt_template_str are None, so there is nothing to format for the LLM. It is a pre-flight configuration error, not an LLM failure.

Source

Thrown at llama-index-core/llama_index/core/program/multi_modal_llm_program.py:71

        multi_modal_llm: Optional[LLM] = None,
        image_documents: Optional[List[Union[ImageBlock, ImageNode]]] = None,
        verbose: bool = False,
        **kwargs: Any,
    ) -> "MultiModalLLMCompletionProgram":
        if multi_modal_llm is None:
            try:
                from llama_index.llms.openai import (
                    OpenAIResponses,
                )  # pants: no-infer-dep

                multi_modal_llm = OpenAIResponses(model="gpt-4.1", temperature=0)
            except ImportError as e:
                raise ImportError(
                    "`llama-index-llms-openai` package cannot be found. "
                    "Please install it by using `pip install `llama-index-llms-openai`"
                )
        if prompt is None and prompt_template_str is None:
            raise ValueError("Must provide either prompt or prompt_template_str.")
        if prompt is not None and prompt_template_str is not None:
            raise ValueError("Must provide either prompt or prompt_template_str.")
        if prompt_template_str is not None:
            prompt = PromptTemplate(prompt_template_str)

        if output_parser is None:
            if output_cls is None:
                raise ValueError("Must provide either output_cls or output_parser.")
            output_parser = PydanticOutputParser(output_cls=output_cls)

        return cls(
            output_parser,
            prompt=cast(PromptTemplate, prompt),
            multi_modal_llm=multi_modal_llm,
            image_documents=image_documents or [],
            verbose=verbose,
        )

View on GitHub (pinned to afd0fef371)

Solutions

1. Pass prompt_template_str or prompt (exactly one) to from_defaults.
2. Add a guard before construction: if not (prompt or prompt_template_str): raise early with your own message.
3. Check that **kwargs forwarding from your wrapper includes the prompt key.

Example fix

# before
program = MultiModalLLMCompletionProgram.from_defaults(
    output_cls=Description,
    image_documents=docs,
)
# after
program = MultiModalLLMCompletionProgram.from_defaults(
    output_cls=Description,
    image_documents=docs,
    prompt_template_str="Describe the image: {context}",
)

if prompt is None and prompt_template_str is None:
    raise ValueError("multimodal program needs a prompt")

def has_prompt_source(prompt, template_str) -> bool:
    return (prompt is None) != (template_str is None)

When it happens

Trigger: Calling MultiModalLLMCompletionProgram.from_defaults(output_cls=..., image_documents=[...]) with neither prompt nor prompt_template_str.

Common situations: Adapting single-modal example code that omitted the prompt argument; prompt variable conditionally set to None; typo in the kwarg name (e.g. prompt_str).

Related errors

• Cannot initialize from a vector store that does not store te
• Must provide either prompt or prompt_template_str.
• Must provide either template or selector.
• Invalid metric name: {metric}
• Cannot specify both similarity_fn and similarity_mode

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/7df35c5cac750046. Report an issue: GitHub.