run-llama/llama_index · error · ValueError

Must provide either output_cls or output_parser.

Error message

Must provide either output_cls or output_parser.

What it means

The multimodal program must know what Pydantic model to parse into. If output_parser is None and output_cls is also None, there is no way to build a parser, so construction fails. Passing either one is required; output_cls alone is enough (a PydanticOutputParser is created for you).

Source

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

                    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,
        )

    @property
    def output_cls(self) -> Type[BaseModel]:
        return self._output_parser.output_cls

    @property
    def prompt(self) -> BasePromptTemplate:
        return self._prompt

View on GitHub (pinned to afd0fef371)

Solutions

1. Pass output_cls=YourPydanticModel.
2. Or pass output_parser=PydanticOutputParser(output_cls=YourPydanticModel).
3. Define a small Pydantic model describing the expected structured output.

Example fix

# before
program = MultiModalLLMCompletionProgram.from_defaults(
    prompt_template_str="Describe: {context}",
    image_documents=docs,
)
# after
class Description(BaseModel):
    text: str

program = MultiModalLLMCompletionProgram.from_defaults(
    output_cls=Description,
    prompt_template_str="Describe: {context}",
    image_documents=docs,
)

if output_parser is None and output_cls is None:
    raise ValueError("define a Pydantic output_cls for the multimodal program")

from pydantic import BaseModel

def is_pydantic_model(cls) -> bool:
    return isinstance(cls, type) and issubclass(cls, BaseModel)

When it happens

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

Common situations: Assuming the program returns raw text (it returns a parsed model); omitting output_cls when refactoring from LLM.complete(); examples trimmed down for brevity.

Related errors

• Output parser must be PydanticOutputParser.
• Cannot initialize from a vector store that does not store te
• Must provide either prompt or prompt_template_str.
• The specified file path is not an accessible image
• The specified URL is not an accessible image

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