{"record":{"id":"2673913b153ad135","repo":"run-llama/llama_index","slug":"structured-predict-expected-a-output-cls-name","errorCode":null,"errorMessage":"structured_predict expected a {output_cls.__name__} instance but got {type(result).__name__}: {result!r}. The LLM failed to produce valid structured output.","messagePattern":"structured_predict expected a (.+?) instance but got (.+?): (.+?)\\. The LLM failed to produce valid structured output\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/llms/llm.py","lineNumber":364,"sourceCode":"        from llama_index.core.program.utils import get_program_for_llm\n\n        dispatcher.event(\n            LLMStructuredPredictStartEvent(\n                output_cls=output_cls, template=prompt, template_args=prompt_args\n            )\n        )\n        program = get_program_for_llm(\n            output_cls,\n            prompt,\n            self,\n            pydantic_program_mode=self.pydantic_program_mode,\n        )\n\n        result = program(llm_kwargs=llm_kwargs, **prompt_args)\n        assert not isinstance(result, list)\n\n        if not isinstance(result, BaseModel):\n            raise TypeError(\n                f\"structured_predict expected a {output_cls.__name__} instance \"\n                f\"but got {type(result).__name__}: {result!r}. \"\n                f\"The LLM failed to produce valid structured output.\"\n            )\n\n        dispatcher.event(LLMStructuredPredictEndEvent(output=result))\n        return result\n\n    @dispatcher.span\n    async def astructured_predict(\n        self,\n        output_cls: Type[Model],\n        prompt: PromptTemplate,\n        llm_kwargs: Optional[Dict[str, Any]] = None,\n        **prompt_args: Any,\n    ) -> Model:\n        r\"\"\"\n        Async Structured predict.","sourceCodeStart":346,"sourceCodeEnd":382,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/llms/llm.py#L346-L382","documentation":"TypeError from the sync structured_predict(): after running the Pydantic program over the LLM output, llama-index asserts the result is a single pydantic BaseModel. If the program returned something else (a string, dict, list of models, or None), the LLM failed to produce valid structured output and the raw non-conforming result is surfaced in the message.","triggerScenarios":"llm.structured_predict(OutputModel, PromptTemplate, ...) where the LLM output cannot be parsed into OutputModel — malformed JSON, an LLM without native function calling falling back to a text-parsing program, output_cls accidentally being a non-pydantic class so the program returns raw text, or a custom pydantic_program whose __call__ returns the wrong type.","commonSituations":"Using non-function-calling LLMs (local/open models) with the default program mode and sloppy JSON output; output_cls passed as a dataclass or TypedDict instead of a BaseModel; low temperature=0 prompts where the model emits prose around JSON; context-length overflow truncating the JSON.","solutions":["Use an LLM with native structured output/function calling (e.g. OpenAI) or pass pydantic_program_mode=PydanticProgramMode.OPENAI / a custom program that validates.","Ensure output_cls is a pydantic BaseModel (not dataclass/TypedDict).","Retry — LLM structured output is nondeterministic; a retry loop with a stricter prompt often fixes one-off malformed JSON.","Log the {result!r} payload from the message to see exactly what the model returned, then adjust the prompt or parser."],"exampleFix":"# before\nclass Output(BaseModel): ...\nresult = llm.structured_predict(Output, prompt_tmpl, query=q)  # local LLM emits prose -> TypeError\n\n# after\nfrom llama_index.core.program.pydantic_program_utils import PydanticProgramMode\nresult = llm.structured_predict(\n    Output, prompt_tmpl, query=q,\n    pydantic_program_mode=PydanticProgramMode.OPENAI,  # or a validating custom program\n)","handlingStrategy":"retry","validationCode":"from pydantic import BaseModel\nassert issubclass(OutputCls, BaseModel), 'output_cls must be a pydantic BaseModel'","typeGuard":"from pydantic import BaseModel\n\ndef is_pydantic_model(cls) -> bool:\n    return isinstance(cls, type) and issubclass(cls, BaseModel)","tryCatchPattern":"for attempt in range(3):\n    try:\n        result = llm.structured_predict(Output, prompt, **kw)\n        break\n    except TypeError:\n        if attempt == 2:\n            raise\n        # tighten the prompt or bump temperature=0 retry","preventionTips":["Use function-calling LLMs or a schema-enforcing program mode for structured output","Verify output_cls subclasses pydantic.BaseModel","Log the offending result payload to tune the prompt","Keep structured-output prompts short and demand raw JSON only"],"tags":["llm","structured-output","pydantic","parsing"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}