> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Output Schema Decode Failed

> The model's final answer did not validate against the configured output_format_schema.

**Surface:** `GET /agents/runs/{id}`, `error.type = "AgentLoopSchemaDecodeFailed"`

## When this error occurs

When the model produces a final answer (no tool calls, just a content message), the workflow
parses the content against the run's output schema. This error means the parse failed:

* **Text mode** (no `output_format_schema` supplied): the model's response could not be
  decoded as the platform's default text-bearing shape (a top-level `text` string).
* **Structured mode** (`output_format_schema` supplied): the model returned JSON that did not
  conform to the caller's schema — for example plain prose instead of a structured object,
  or an object missing a required field.
* The model returned multiple text blocks; only the first is considered.

## How to fix

* **Tighten the system prompt** — explicitly tell the model "respond with a JSON object
  matching this schema; do not include any other text." Models often add prose when the schema
  isn't reinforced in instructions.
* **Simplify the schema** — Bedrock's structured-output sampler enforces a subset of Draft
  2020-12; deeply nested or exotic constructs (e.g. unconstrained `oneOf`) are more likely to
  trip the decoder.
* **Increase `max_tokens`** — sometimes the model is truncated mid-JSON.
* **Inspect the last assistant turn** in the message stream to see exactly what the model
  produced.

<Note>
  Before V2026.x, every caller schema had to declare a top-level `text: string` because the
  workflow unconditionally extracted `structuredOutput.text`. That requirement is gone:
  structured-mode runs now return the caller's schema verbatim on `final_structured_output`,
  and text-mode runs return a plain string on `final_text`. See
  [Agent Conversations](/reference/architecture/agent-conversations) for the full response
  contract.
</Note>