Skip to main content

Troubleshoot workflow errors

Learn how to handle errors and debug unexpected behavior in a workflow.

As you build workflows of increasing complexity that interact with more data sources, it's important to handle errors and debug unexpected behavior effectively. You can configure Resource query blocks as error handlers to perform an action in the event of an error. If an error occurs, you can review its run logs to investigate and resolve the problem.

Configure error handling​

You can configure the following block types to operate as global error handlers that execute if an error occurs anywhere during a workflow run. Note that workflows continue to run even after an error is triggered.

To configure a block for error handling, click ••• and select Add global error handler. Error handlers do not need to be part of the control flow and will execute if the workflow detects an error.

Configure a global error handler

Retry blocks​

For more granular error handling, you can configure retry settings per block for the above block types. This allows your workflow to automatically retry failed blocks with a specified schedule. Setting an exponential backoff can be especially useful for retrying blocks that query rate-limited APIs or data sources.

To configure retry settings, select Settings on the block. See the block settings, e.g., Resource query settings, to learn more.

Configure retry settings

Retrieve the workflow error details​

You can reference workflowContext anywhere in your workflow to include workflow details. For example, you can get the workflow name using {{ workflowContext.name }}. This can be useful for distinguishing between workflows that send notifications or including details about when the workflow's actions were last completed.

If a workflow fails, Retool makes the error information available at workflowContext.currentRun.error.message. You can use this when configuring an error handler to log errors from the current run. For example, a Response block can return a 500 status with the error message.

Response block returning an error

Review and debug runs​

You can use Ask AI to debug JavaScript, SQL, or GraphQL queries using AI-powered debugging.

Retool logs every successful and failed run of a workflow. Click Run history in the status bar to debug workflows. The Run history panel contains a list of recent runs, each with their date, time, their status. You can then view the status of each block to see where a failure may have occurred.

Run logs can help troubleshoot problems with queries, such as malformed SQL statements or invalid JavaScript. You can filter log entries to show only error, success, or info entries. Keep in mind that queries are considered successful if they didn't return an error. A workflow cannot determine if its actions produced the results you expected.

Admins can enable and update the retention period for Run History data from Settings > Advanced > Workflows: Enable Data Retention. The default retention period is 30 days, and the maximum retention period is 90 days.

Monitor usage with run logs​

Retool calculates workflow usage and billing based on runs. You can view information about workflow runs by reviewing the logs.