{"record":{"id":"c0f5119503546973","repo":"run-llama/llama_index","slug":"astructured-predict-expected-a-output-cls-name","errorCode":null,"errorMessage":"astructured_predict expected a {output_cls.__name__} instance but got {type(result).__name__}: {result!r}. The LLM failed to produce valid structured output.","messagePattern":"astructured_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":432,"sourceCode":"\n        dispatcher.event(\n            LLMStructuredPredictStartEvent(\n                output_cls=output_cls, template=prompt, template_args=prompt_args\n            )\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 = await program.acall(llm_kwargs=llm_kwargs, **prompt_args)\n        assert not isinstance(result, list)\n\n        if not isinstance(result, BaseModel):\n            raise TypeError(\n                f\"astructured_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    def _structured_stream_call(\n        self,\n        output_cls: Type[Model],\n        prompt: PromptTemplate,\n        llm_kwargs: Optional[Dict[str, Any]] = None,\n        **prompt_args: Any,\n    ) -> Generator[\n        Union[Model, List[Model], \"FlexibleModel\", List[\"FlexibleModel\"]], None, None\n    ]:\n        from llama_index.core.program.utils import get_program_for_llm","sourceCodeStart":414,"sourceCodeEnd":450,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/llms/llm.py#L414-L450","documentation":"Async counterpart of structured_predict: astructured_predict() awaits program.acall() and then requires a pydantic BaseModel instance. If the program yields a non-BaseModel (string, dict, None), the LLM failed to generate valid structured output and this TypeError is raised with the offending value.","triggerScenarios":"await llm.astructured_predict(OutputModel, prompt, ...) with a non-function-calling model whose output fails JSON parsing; output_cls that is not a pydantic class; a custom async program returning raw text; truncated JSON from exceeding the context window.","commonSituations":"Async services (FastAPI backends) doing structured extraction with local/open-source models; occasional malformed JSON under load; switching from OpenAI to a provider without native JSON mode.","solutions":["Switch to a function-calling LLM or a program mode that enforces the schema.","Verify output_cls subclasses pydantic.BaseModel.","Add a bounded retry around astructured_predict for transient malformed output.","Inspect the reported {result!r} to tune the prompt (e.g. demand raw JSON only, no markdown fences)."],"exampleFix":"# before\nresult = await llm.astructured_predict(Output, prompt_tmpl, query=q)  # raises TypeError on bad JSON\n\n# after\nfor attempt in range(3):\n    try:\n        result = await llm.astructured_predict(Output, prompt_tmpl, query=q)\n        break\n    except TypeError:\n        if attempt == 2:\n            raise","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 = await llm.astructured_predict(Output, prompt, **kw)\n        break\n    except TypeError:\n        if attempt == 2:\n            raise","preventionTips":["Prefer providers with native JSON/function-calling modes for async structured extraction","Validate output_cls is a BaseModel before calling","Add bounded retries with jitter in async services","Watch context length so JSON is not truncated"],"tags":["llm","structured-output","pydantic","async"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}