Troubleshooting
A run failed
How to find a failed run in History, read its error and fix the usual causes.
A run fails when a step cannot finish: a tool errors, an app is not connected, the workspace has no credits or the plan does not allow a step. Every run is saved, so you can read what happened after the fact.
Symptoms#
- The agent stops partway or gives an empty or generic answer.
- A workflow ends early, or a batch row shows Failed.
- A scheduled run did nothing.
- You see an error banner after clicking publish, such as “Validation failed. Please fix the errors highlighted on the components.”
Find the run in History#
- Click History in the sidebar.
- Turn on the Error messages filter to list only sessions that contained an error. You can also filter by Agent or workflow and by chatbot.
- Open a session. Use Plain or Verbose to change how much detail you see.
- Read down the events. They are labelled User message, Chatbot output, System message, Chat hook, Tool Call and Agent Query. Look at the Tool Call events for the one that reports the error.
The metrics panel above the table (Show metrics) charts Total errors over time. Your plan limits how far back the history goes. See plans and limits. For batch runs, the table has Status and Error columns, and Re-run Failed or Retry row run the failed rows again.
Common errors and fixes#
| What you see | Cause | Fix |
|---|---|---|
| “Insufficient credits to perform this action. Please recharge your credits.” | The balance is empty | Out of credits |
| “Workspace credit limit reached” | A workspace spending limit | Raise it under Settings → Credits |
| “NAME is not configured. Please set up the integration first.” | The step needs an app that is not connected | Connect it under Integrations |
| “…is connected but is missing the permissions it requires. Please reconnect the integration and grant the additional permissions.” | The connection lacks a permission | Reconnect and accept every permission |
| “…requires re-authorization. The refresh token is expired or revoked. Please reconnect the integration.” | The login expired or was revoked | Reconnect the account |
| “Component NAME can only be used with … plan” | The step is not in your plan | Replace the step or upgrade |
| “Allowed limit of … reached. Please upgrade your plan.” | You hit a plan cap while creating something | Remove one or upgrade |
| “Validation failed. Please fix the errors highlighted on the components.” | A step is missing required settings | Fix the highlighted steps, then publish again |
Scheduled runs#
If the workspace ran out of credits, the system switches the schedule off instead of retrying forever. Open it and enable it again once you have credits. See schedules.
Fix it#
- Find the failed session and copy the exact error.
- Match it to the table, apply the fix and run the same input again.
- If the error comes from an external service and you cannot tell why, test the step on its own from the canvas. See testing and run logs.