Retool Workflows error handling and debugging

Learn how to handle workflow errors and debug unexpected behavior.

πŸŽ‰

beta

Retool Workflows is currently in public beta for Retool Cloud organizations. Sign up to get started β†’

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 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.

Workflow performance best practices

Workflow performance issues can be difficult to replicate, especially when they involve external factors. The following best practices can help avoid problems and reduce the need to debug workflows.

Avoid querying large datasets

Queries that retrieve large amounts of data impact workflow performance. The more data a workflow query requests, the longer it can take for the resource to complete the operation.

Query blocks have a maximum time out of two minutes. Where possible, write queries that return only the results that the workflow needs (e.g., APIs support pagination or WHERE SQL query clauses).

Build workflows to perform specific tasks

Workflows time out after ten minutes and have 258MB of memory available. To avoid timeouts, build separate workflows to perform specific tasks instead of a single workflow that performs them together.

Trigger workflows only when needed

Workflows are rate-limited and have a minimum interval of one minute. You cannot trigger a workflow to run more frequently than this. Each workflow must also complete a run (whether successful or not) before it can be run again. For example, if a workflow takes two minutes to complete, it can only be triggered every two minutes.

Whether you schedule a workflow to run automatically or trigger it using a webhook event, make sure that the workflow triggers only when it should run. This also helps reduce the amount of interactions a workflow has with your data source, which can reduce operational costs.

Error handlers

You can configure a Query block to run only if an error occurs when the workflow is run. Click β«Ά and select Use as global error handler. Query blocks configured as error handlers work independently from other blocks in your workflow and are limited to one per workflow. They're also not connected to pass data.

This is useful if you want to receive a notification or to perform an action only if a workflow fails.

Error handler blockError handler block

Run logs

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.

Run logsRun 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.

...
[Thu Aug 11 2022 17:46:59 GMT-0700] --- Running query: startTrigger ---
[Thu Aug 11 2022 17:46:59 GMT-0700] Memory usage: 31.5 MB
[Thu Aug 11 2022 17:46:59 GMT-0700] --- Running query: branch1 ---
[Thu Aug 11 2022 17:46:59 GMT-0700] Evaluating JS query: branch1
[Thu Aug 11 2022 17:46:59 GMT-0700] --- Successfully finished running query: branch1 ---
[Thu Aug 11 2022 17:46:59 GMT-0700] Memory usage: 31.6 MB
[Thu Aug 11 2022 17:46:59 GMT-0700] --- Skipping query: query4 ---
[Thu Aug 11 2022 17:46:59 GMT-0700] Memory usage: 31.6 MB
[Thu Aug 11 2022 17:46:59 GMT-0700] --- Running query: query5 ---
[Thu Aug 11 2022 17:46:59 GMT-0700] Evaluating JS query: query5
[Thu Aug 11 2022 17:46:59 GMT-0700] [log] {
value: { severity: '1', product_area: 'some text' },
metadata: null,
data: null
}
[Thu Aug 11 2022 17:46:59 GMT-0700] --- Successfully finished running query: query5 ---
[Thu Aug 11 2022 17:56:58 GMT-0700] The request timeout after 598985 ms
...

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.

Workflow context

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.