Skip to main content

Troubleshoot workflow errors

Learn how to handle errors and debug unexpected behavior in Retool Workflows.

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 error handlers that execute if an error occurs during a workflow run:

  • Resource query
  • Code
  • Smart
  • Loop
  • Response

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

You can configure multiple blocks as error handlers to handle different errors.

Retrieve error information from WorkflowContext​

You can reference workflowContext anywhere in your workflow to include workflow details, such as its name or when it last ran (e.g., {{ 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 run logs​

tip

You can debug errors with JavaScript Code blocks using AI-powered debugging.

Retool logs every successful and failed run of a workflow. The Run history tab contains a list of recent runs that include the date and time, and their status.

Review logs

Click Logs in the lower left of the editor to show the Logs panel. By default, the panel displays the log for the most recent run. You can click on any recent run to display its log.

Each log contains detailed information about what the workflow is doing and if each Query block successfully ran. If a workflow did not run successfully, the log includes details about the error and when it occurred.

...
[Fri May 19 2023 13:55:04 GMT-0700] --- Running query: startTrigger ---
[Fri May 19 2023 13:55:04 GMT-0700] Evaluating JS query: startTrigger
[Fri May 19 2023 13:55:04 GMT-0700] --- Successfully finished running query: startTrigger ---
[Fri May 19 2023 13:55:04 GMT-0700] --- Running query: getUsers ---
[Fri May 19 2023 13:55:04 GMT-0700] Error evaluating getUsers: relation "uusers" does not exist
[Fri May 19 2023 13:55:04 GMT-0700] --- Failed running query: getUsers ---
[Fri May 19 2023 13:55:04 GMT-0700] --- Hit failure ---
[Fri May 19 2023 13:55:05 GMT-0700] --- Running query: webhookReturn1 ---
[Fri May 19 2023 13:55:05 GMT-0700] Evaluating JS query: webhookReturn1
[Fri May 19 2023 13:55:05 GMT-0700] --- Successfully finished running query: webhookReturn1 ---
[Fri May 19 2023 13:55:05 GMT-0700] --- Successfully finished running the workflow ---
...

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

Monitor usage with run logs​

Retool calculates workflow usage and billing based on throughput. You can view the data consumed for each run of a workflow by reviewing the logs.

Workflows Run History tab