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

LLMTextCompletionProgram.from_defaults requires exactly one prompt source: either a formatted prompt_template_str string or a pre-built BasePromptTemplate. This error fires when both arguments are None, leaving the program with no prompt to format. It is raised before any LLM call, so it is purely a caller configuration mistake.

Source

Thrown at llama-index-core/llama_index/core/program/llm_program.py:63

        self._prompt = prompt
        self._verbose = verbose

        self._prompt.output_parser = output_parser

    @classmethod
    def from_defaults(
        cls,
        output_parser: Optional[BaseOutputParser] = None,
        output_cls: Optional[Type[Model]] = None,
        prompt_template_str: Optional[str] = None,
        prompt: Optional[BasePromptTemplate] = None,
        llm: Optional[LLM] = None,
        verbose: bool = False,
        **kwargs: Any,
    ) -> "LLMTextCompletionProgram[Model]":
        llm = llm or Settings.llm
        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)

        # decide default output class if not set
        if output_cls is None:
            if not isinstance(output_parser, PydanticOutputParser):
                raise ValueError("Output parser must be PydanticOutputParser.")
            output_cls = output_parser.output_cls
        else:
            if output_parser is None:
                output_parser = PydanticOutputParser(output_cls=output_cls)

        return cls(
            output_parser,
            output_cls,
            prompt=cast(PromptTemplate, prompt),

View on GitHub (pinned to afd0fef371)

Solutions

1. Pass exactly one of prompt_template_str='...' or prompt=PromptTemplate(...) to from_defaults.
2. If building the prompt dynamically, assert it is not None before calling from_defaults.
3. Do not pass both arguments — a sibling check at line 65 rejects that combination too.

Example fix

// before
program = LLMTextCompletionProgram.from_defaults(
    output_cls=Album,
    verbose=True,
)
// after
program = LLMTextCompletionProgram.from_defaults(
    output_parser=PydanticOutputParser(output_cls=Album),
    prompt_template_str="Generate an example album: {album_name}",
    verbose=True,
)

def build_program(output_cls, prompt=None, prompt_template_str=None, **kw):
    if prompt is None and prompt_template_str is None:
        raise ValueError("program requires prompt or prompt_template_str")
    return LLMTextCompletionProgram.from_defaults(
        output_parser=PydanticOutputParser(output_cls=output_cls),
        prompt=prompt,
        prompt_template_str=prompt_template_str,
        **kw,
    )

from typing import Optional
from llama_index.core.prompts import BasePromptTemplate

def has_prompt_source(prompt: Optional[BasePromptTemplate],
                      template_str: Optional[str]) -> bool:
    return (prompt is None) != (template_str is None)

When it happens

Trigger: Calling LLMTextCompletionProgram.from_defaults(output_parser=..., output_cls=...) with neither prompt= nor prompt_template_str=. Also happens when the prompt variable is accidentally passed under a different kwarg name or is None due to earlier logic.

Common situations: Copy-pasting an example that used prompt_template_str but renaming the argument; passing prompt=None because a conditional upstream never assigned it; migrating from an older API where output_cls alone was enough.

Related errors

• 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
• Unknown oversized document strategy: {strategy}

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