run-llama/llama_index · error · ValueError

Structured output extraction failed: the LLM's tool call cou

Error message

Structured output extraction failed: the LLM's tool call could not be parsed into {self._output_cls.__name__}. Error: {error_detail}

What it means

Error "Structured output extraction failed: the LLM's tool call could not be parsed into {self._output_cls.__name__}. Error: {error_detail}" thrown in run-llama/llama_index.

Source

Thrown at llama-index-core/llama_index/core/program/function_program.py:239

                "LLM did not return any tool calls for structured output. "
                "The model was expected to call a function to produce a "
                f"{self._output_cls.__name__} object, but instead returned "
                f"plain text: {agent_response.response!r}. "
                "This can happen when the LLM provider does not honor "
                "tool_choice='required'. Consider using a different model or "
                "switching to PydanticProgramMode.LLM to use text-based "
                "output parsing instead."
            )

        outputs: List[Model] = []
        for source in agent_response.sources:
            raw = source.raw_output
            if source.is_error:
                # The tool call failed (e.g. Pydantic validation error).
                # Surface the original exception with context instead of
                # silently returning a string that will crash downstream.
                error_detail = str(source.exception) if source.exception else str(raw)
                raise ValueError(
                    f"Structured output extraction failed: the LLM's tool "
                    f"call could not be parsed into "
                    f"{self._output_cls.__name__}. "
                    f"Error: {error_detail}"
                )
            if not isinstance(raw, BaseModel):
                raise TypeError(
                    f"Structured output extraction failed: expected a "
                    f"{self._output_cls.__name__} instance but got "
                    f"{type(raw).__name__}: {raw!r}. "
                    f"This may indicate a bug in the LLM integration's "
                    f"tool call handling."
                )
            outputs.append(cast(Model, raw))

        if allow_parallel_tool_calls:
            return outputs
        else:

View on GitHub (pinned to afd0fef371)

Solutions

1. Inspect error_detail and fix the output_cls schema or the tool call arguments produced by the model.
2. Retry with a more capable model or simplify the pydantic schema.

When it happens

Trigger: Thrown at llama-index-core/llama_index/core/program/function_program.py:239 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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