What causes "Output parser must be PydanticOutputParser." in run-llama/llama_index?

Pass output_cls=YourPydanticModel explicitly; the factory then wraps it in a PydanticOutputParser for you.

run-llama/llama_index · error · ValueError

Output parser must be PydanticOutputParser.

Error message

Output parser must be PydanticOutputParser.

What it means

When output_cls is omitted, from_defaults tries to infer the output class from output_parser.output_cls, which only exists on PydanticOutputParser. Any other BaseOutputParser subclass (or None) triggers this error. The program needs a Pydantic model class to type-check parsed results.

Source

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

        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),
            llm=llm,
            verbose=verbose,
        )

    @property
    def output_cls(self) -> Type[Model]:
        return self._output_cls

    @property

View on GitHub (pinned to afd0fef371)

Solutions

Pass output_cls=YourPydanticModel explicitly; the factory then wraps it in a PydanticOutputParser for you.
Or use output_parser=PydanticOutputParser(output_cls=YourPydanticModel) so the class can be inferred.
If you truly need a custom parser, it must be a PydanticOutputParser or you must supply output_cls separately.

Example fix

// before
program = LLMTextCompletionProgram.from_defaults(
    output_parser=MyCustomParser(),
    prompt_template_str="...",
)
// after
program = LLMTextCompletionProgram.from_defaults(
    output_parser=PydanticOutputParser(output_cls=Album),
    prompt_template_str="...",
)

Defensive patterns

Strategy: type-guard

Validate before calling

from llama_index.core.output_parsers import PydanticOutputParser

if output_cls is None and not isinstance(output_parser, PydanticOutputParser):
    raise ValueError("supply output_cls or a PydanticOutputParser")

Type guard

from llama_index.core.output_parsers import PydanticOutputParser

def parser_has_output_cls(parser) -> bool:
    return isinstance(parser, PydanticOutputParser) and parser.output_cls is not None

Prevention

Always pass output_cls explicitly in program factories; it doubles as documentation.
Keep custom output parsers for text pipelines, not Pydantic programs.

When it happens

Trigger: Calling from_defaults(output_parser=CustomOutputParser(), prompt_template_str=...) with no output_cls, where CustomOutputParser is a plain BaseOutputParser subclass; or passing output_parser=None and no output_cls.

Common situations: Writing a custom output parser for non-Pydantic output; passing a plain output parser while assuming the factory infers the class; refactoring code that previously always supplied output_cls.

Related errors

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