> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.runtype.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server. # Agent execution failures > Diagnose Agent runs that fail, stop early, or return an empty answer Use the run's status and stop reason to find why an Agent run failed or stopped early, then apply the matching fix. ## Find the failed run The Agent editor lists every run of the Agent. To open a failed run, follow these steps: 1. Open the Agent, and then select the **Runs** tab. 2. Click **Failed** to show only failed runs. 3. Select a run. The transcript and timeline open, with each tool call and its result. A run that stops at a limit can still show **Completed**. When a run ends for any reason other than a clean finish, its row in **Runs** shows the stop reason, for example **Max Turns** or **Timeout**. Check the stop reason as well as the status when an answer is missing or incomplete. To search across Agents, open **Logs**, set **Type** to **Agent**, and set **Status** to **Failed**. For what the execution details show, see [Working with logs](/user-guide/logs/working-with-logs#agent-executions). ### Find failures from code To list an Agent's failed log entries from the CLI, run this command: ```bash runtype logs list --agent YOUR_AGENT_ID --status failed ``` Replace `YOUR_AGENT_ID` with the ID of the Agent, which starts with `agent_`. To list the Agent's failed runs through the API, send a `GET` request to `/v1/runs` with the `agentId` and `status` query parameters. The API key needs the `AGENTS:READ` permission: ```bash curl "https://api.runtype.com/v1/runs?agentId=YOUR_AGENT_ID&status=failed" \ -H "Authorization: Bearer YOUR_API_KEY" ``` Replace `YOUR_API_KEY` with your Runtype API key. Each row carries `status`, `stopReason`, and `executionId`. To see which tool calls failed in one run, send a `GET` request to `/v1/agents/YOUR_AGENT_ID/executions/YOUR_EXECUTION_ID/tool-calls`. Each entry in `toolCalls` carries the tool's `status` and `errorMessage`. Replace `YOUR_EXECUTION_ID` with the run's `executionId`. When you run an Agent with a streamed response, each failed tool call sends a `tool_complete` event with `success` set to `false` and the message in `error`. A failed run ends with an `execution_error` event that carries `error` and `stopReason`. A run that ends normally, including one that stops at a limit, ends with `execution_complete`. With `streamResponse` set to `false`, the JSON response carries `success`, `status`, `stopReason`, and, for a failed run, `error`. ## Read the stop reason The stop reason tells you why the run ended. The following table lists the label in **Runs**, the `stopReason` value in API responses, the run status, and what each one means: | Label | `stopReason` | Status | Meaning | | ------------------------ | ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ | | **Complete** | `complete` | Completed | The model finished its turn with an answer. | | **Max Turns** | `max_turns` | Completed | The run used every turn in **Max turns** before the model finished. | | **Max Cost** | `max_cost` | Completed | The run's cost reached **Cost budget (USD)**. | | **Timeout** | `timeout` | Completed | The run's time budget ran out between two turns. | | **Max Tokens** | `length` | Failed | The model reached its output token limit while it wrote a tool call. | | **Error** | `error` | Failed | A model error failed the run, or the time budget ran out during a model or tool call. The error message names the cause. | | **Cancelled** | `cancelled` | Cancelled | A cancel request stopped the run. | | **Interrupted** | `interrupted` | Interrupted | The run stopped before it finished, without an error from the model or a tool. | | **Awaiting Approval** | `approval_required` | Paused | The run waits for a person to approve or deny a tool call. | | **Awaiting Tool Result** | `client_tool_required` | Paused | The run waits for your client to run a tool and send the result. | A paused run isn't a failure. For how to continue it, see [Pause and resume on an agent dispatch](/developer-guides/guides/runtime-tools#pause-and-resume-on-an-agent-dispatch). ## Diagnose common failures Match the stop reason and the error message to one of the following causes. ### Model error A model call fails when the provider rejects or can't complete the request. The Agent's **Error handling** setting runs first. By default, it retries the model twice, after 5 seconds and then after 10 seconds. For the other modes and fallback types, see [Error handling](/user-guide/agents/creating-and-configuring-agents#error-handling). If the turn still fails and produces no text and no tool calls, the loop can try another turn. The run ends with the **Error** stop reason in these cases: * The provider rejected the API key or denied access to the model. The run ends after one such turn. * The provider was rate limited, overloaded, or returned a server error on three turns in a row. * Any other model error occurred on two turns in a row. * The failed turn was the last turn that **Max turns** allowed. Without **Agent loop**, the run has one turn. The error message starts with `Agent loop aborted after` or `Agent loop ended because its final turn failed with a model error`, followed by the provider's message. Check the provider's message against these causes: * **The provider API key is invalid.** Verify the key in **Settings > Models > Providers**. * **The model isn't available.** Select a configured model, or add a **Different model** fallback. For details, see [Model not available](/user-guide/troubleshooting-faq/common-errors-and-solutions#model-not-available). * **The provider rate limit is reached.** Add a **Retry** fallback with a **Delay**, or use your own provider key. * **Platform credit or your spend cap is used up.** For the codes and fixes, see [Spend limit reached](/user-guide/troubleshooting-faq/common-errors-and-solutions#spend-limit-reached). * **The input exceeds the model's context length.** Keep **Context compaction** on, or select a model with a larger context length. For details, see [Context compaction](/user-guide/agents/creating-and-configuring-agents#context-compaction). ### Output cut off at the token limit The **Max Tokens** stop reason means that the model reached its output token limit while it wrote a tool call. Runtype reports that tool call as failed. If turns remain, the Agent continues. On the last turn, the run fails, and the response still carries any text that the Agent wrote before the cutoff. To fix it, raise **Max output tokens** in the Agent's model settings. A thinking model uses the same budget for its reasoning and its answer, so it needs a higher limit. For details, see [Tool call limits](/user-guide/agents/agent-tools#tool-call-limits). ### Run ends at Max Turns with no answer **Max Turns** means that the model was still calling tools when the run used its last turn. The final answer can be empty. Check these settings: * Raise **Max turns** if the task needs more steps. The dashboard control accepts 2 to 20. * Set **Tool call strategy** to **Auto**. With **Required**, the model must call a tool on every turn and can't return a text answer. * Read the transcript for repeated calls to the same tool. Repeated calls often mean that a tool description or a tool error message doesn't tell the model what to do next. ### Run stops at the cost budget **Max Cost** means that the run's cost reached **Cost budget (USD)**. Runtype checks the budget after each turn, so the final cost can exceed the budget by the cost of one turn. Raise the budget, lower **Max turns**, or select a less expensive model. ### Timeout A run has a time budget, and the stop reason depends on when the budget runs out: * **Between turns**: the run ends with the **Timeout** stop reason and the **Completed** status. * **During a model or tool call**: the run fails with the **Error** stop reason. The message starts with `Agent turn exceeded the`, followed by the budget in milliseconds. To fix a timeout, reduce the work in one run. Lower **Max turns**, replace a slow tool with a faster one, or move a long phase into a detached subagent, which has its own budget. For details, see [Run long phases as detached subagents](/user-guide/flows/timeouts-and-long-running-work#run-long-phases-as-detached-subagents). An Agent that runs in a Flow's **Execute Agent** step also stops at the step timeout, which defaults to 30 seconds. For details, see [Timeout](/user-guide/troubleshooting-faq/flow-execution-failures#timeout). ### Tool call failure A failed tool call doesn't fail the run. The Agent receives the error message and a failure class, such as `auth`, `timeout`, or `invalid_args`, and can retry, correct its arguments, or choose another tool. Open the run and select the failed tool call to see its input and error. Check these causes: * **`auth`**: Verify the secret or API key that the tool uses. * **`invalid_args`**: Improve the parameter descriptions so the model sends valid values. * **`timeout`**: Make the tool faster, or raise its timeout within the tool type's limit. * **`not_configured`**: Finish the tool's setup, such as a missing secret or MCP server connection. If the Agent retries a failing tool until it runs out of turns, fix the tool, then write an error message that tells the model what to do instead. For all failure classes, see [Error handling](/user-guide/agents/agent-tools#error-handling). ### Request refused before the run starts Some errors stop the request before the Agent runs, so no run appears in **Runs**. The following table lists the most common ones: | Status | Code | Fix | | ------ | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `404` | `AGENT_NOT_DEPLOYED` | Deploy a version to the `live` alias, or name a version in the request. See [Agent versioning and publishing](/user-guide/agents/agent-versioning-and-publishing). | | `409` | `CONVERSATION_BUSY` | Another run is active in the same conversation. Wait for `Retry-After`, or steer the active run. See [Steer an active agent execution](/developer-guides/guides/live-message-steering). | | `402` | `SPEND_LIMIT_EXCEEDED` or `PLATFORM_KEY_SPEND_EXCEEDED` | Change your billing settings. See [Spend limit reached](/user-guide/troubleshooting-faq/common-errors-and-solutions#spend-limit-reached). | A run from a Schedule, Batch, Eval, or webhook can't answer a tool approval prompt. If the Agent has **Tool approval** on, those runs fail with an error that names the tool approval policy. For details, see [Require approval for tool calls](/user-guide/agents/agent-tools#require-approval-for-tool-calls). ## Verify a fix After you change the Agent, run the same input again. Follow these steps: 1. On the **Runs** tab, select the failed run. 2. Click **Re-run with current version**. The test sheet opens and runs the Agent with your current edits. 3. Send the input from the failed run. 4. Compare the new run's stop reason and transcript with the failed run. **Re-run** repeats the run with the same input messages. Tool calls repeat too, so a tool that sends messages or writes data runs again. The dashboard asks you to confirm first. To keep the failure from coming back, capture the failed run as an eval case before you fix it. For the full workflow, see [Improving your agents from production traces](/developer-guides/guides/improving-agents-from-production). ## Next steps * [Creating and configuring agents](/user-guide/agents/creating-and-configuring-agents): set the loop, error handling, and context settings * [Agent tools](/user-guide/agents/agent-tools): set tool call limits and write tool descriptions * [Working with logs](/user-guide/logs/working-with-logs): filter and inspect Agent executions * [Flow execution failures](/user-guide/troubleshooting-faq/flow-execution-failures): diagnose failed Flow steps * [Common errors and solutions](/user-guide/troubleshooting-faq/common-errors-and-solutions): fix specific error messages