Agent execution failures
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:
- Open the Agent, and then select the Runs tab.
- Click Failed to show only failed runs.
- 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.
Find failures from code
To list an Agent’s failed log entries from the CLI, run this command:
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:
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:
A paused run isn’t a failure. For how to continue it, see 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.
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.
- 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.
- 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.
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.
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.
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.
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.
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:
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.
Verify a fix
After you change the Agent, run the same input again. Follow these steps:
- On the Runs tab, select the failed run.
- Click Re-run with current version. The test sheet opens and runs the Agent with your current edits.
- Send the input from the failed run.
- 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.
Next steps
- Creating and configuring agents: set the loop, error handling, and context settings
- Agent tools: set tool call limits and write tool descriptions
- Working with logs: filter and inspect Agent executions
- Flow execution failures: diagnose failed Flow steps
- Common errors and solutions: fix specific error messages