Retool Agents troubleshooting
Troubleshooting common issues with Retool Agents.
| Agents Availability | |||
|---|---|---|---|
| Cloud | Public beta | ||
| Self-hosted Edge 3.234 or later | Public beta | ||
| Self-hosted Stable 3.253 or later | Public beta | ||
Use this page to diagnose and resolve common issues with Retool Agents.
Why are agent logs unavailable?
Logs are retained for 30 days. After that, they expire and can no longer be retrieved. If you see "Agent logs are no longer available," the run is older than the retention window.
For runs within the retention window, logs may occasionally be unavailable due to a storage error. If this happens, check the monitoring page for high-level run information.
Why does my agent stop before completing the task?
The agent may have reached its iteration limit. The default is 10 iterations, and the maximum is 50. If your task requires more steps, increase the iteration limit in the agent's configuration.
The agent may also be approaching the model's context window. Agents cap token usage at 90% of the model's limit to leave a safety buffer. If tool outputs are large, consider reducing the data returned from each tool.
Why is the agent calling the wrong tool?
Tool descriptions guide the model's selection. If the agent consistently picks the wrong tool, the descriptions may be too similar, too vague, or missing key context about when each tool should be used. Update the descriptions to be more specific and distinct.
You can also add explicit guidance in the agent's instructions, such as "Use the search_orders tool for order lookups and the search_customers tool for account lookups."
Why is a tool call timing out?
The default tool handler timeout is 10 seconds. If your tool regularly exceeds this, investigate whether the underlying query or API call can be optimized. If the operation is inherently long-running (for example, a batch job), consider wrapping it in a workflow and using the workflow as a tool instead, which supports longer timeouts.
Why did I hit the tool output size limit?
Tool outputs are limited to 1 MB. If a tool returns too much data, the run can fail before the agent can continue.
To avoid this:
- Return only the fields needed for the current step.
- Filter aggressively (date window, status, IDs) before returning results.
- Paginate large datasets instead of returning everything at once.
- Summarize large payloads and fetch details only when required.
See Tool limitations and Prompting guidance for recommended patterns.
Can agents execute tools in parallel?
Not currently. Agents execute one tool at a time, sequentially. If your task requires data from multiple independent sources, consider fetching that data in a single tool (for example, a workflow that makes multiple queries) rather than relying on the agent to call multiple tools in sequence.