run-llama/llama_index · error · TypeError

Structured output extraction failed: expected a {self._outpu

Error message

Structured output extraction failed: expected a {self._output_cls.__name__} instance but got {type(raw).__name__}: {raw!r}. This may indicate a bug in the LLM integration's tool call handling.

What it means

Error "Structured output extraction failed: expected a {self._output_cls.__name__} instance but got {type(raw).__name__}: {raw!r}. This may indicate a bug in the LLM integration's tool call handling." thrown in run-llama/llama_index.

Source

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

                "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:
            if len(outputs) > 1:
                _logger.warning(
                    "Multiple outputs found, returning first one. "
                    "If you want to return all outputs, set output_multiple=True."
                )

            return outputs[0]

View on GitHub (pinned to afd0fef371)

Solutions

1. Update the LLM integration so its tool call handling returns the output_cls instance.
2. Validate output_cls matches what the integration's function program produces.

When it happens

Trigger: Thrown at llama-index-core/llama_index/core/program/function_program.py:246 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/283c525042d9b11b. Report an issue: GitHub.