Troubleshooting workflows

Diagnose and resolve common issues with Retool Workflows.

Retool 4.0.0 Stable

All plans

Use this page to diagnose and resolve common issues with Retool Workflows.

Why did my workflow time out?

Retool enforces timeout limits at both the workflow and block level. If a timeout is exceeded, Retool terminates the run.

Workflow-level timeouts:

Trigger type	Timeout
Asynchronous	30 hours
Synchronous (webhook or classic app trigger)	15 minutes to reach the first Response block; remaining blocks run asynchronously
Run by a Run Workflow block	3 minutes

Block-level timeouts:

Block type	Default	Maximum
Code block	10 seconds	10 minutes (cloud), 24 days (self-hosted)
Resource query block	10 seconds	10 minutes (asynchronous), 2 minutes (synchronous)
AI Action block	—	120 seconds
Loop block (per iteration)	—	2 minutes

You can configure the 10-second default for synchronous Code blocks in Settings on the block. Asynchronous Code blocks and Resource query blocks (both synchronous and asynchronous) can run up to 120 seconds before timing out.

If a block is timing out, increase its timeout in Settings on the block. For operations that consistently exceed block limits, consider breaking the work into smaller steps or restructuring the workflow to use asynchronous execution by placing a Response block earlier in the flow.

Refer to Workflow limits for a complete list of timeout values.

Why is my workflow failing with a memory error?

On cloud, a single workflow run can use up to 2.5 GB of memory. If a workflow exceeds this limit, Retool terminates the run.

Common causes include:

• Fetching large datasets without pagination.
• Accumulating data across many loop iterations without releasing previous results.
• Processing large files or binary content in memory.

To reduce memory usage:

• Paginate database queries and API calls instead of fetching all records at once.
• Use a Loop block to process data in batches, writing intermediate results to a database rather than holding them in memory.
• Avoid assigning large objects to variables that persist across blocks when they are no longer needed.

Example: paginating a query to avoid memory limits

Instead of fetching all rows at once:

// Avoid: loads entire table into memory
return await db.query('SELECT * FROM events');

Fetch rows in pages:

const pageSize = 1000;
let offset = 0;
let allRows = [];

while (true) {
    const rows = await db.query(`SELECT * FROM events LIMIT ${pageSize} OFFSET ${offset}`);
    if (rows.length === 0) break;
    allRows = allRows.concat(rows);
    offset += pageSize;
}

return allRows;

On self-hosted instances, memory limits are not enforced by default. To enable them, set WORKFLOW_MONITOR_PROCESS_ENABLED to true on the code-executor container. When enabled, the memory limit defaults to 2,500 MB, configurable via WORKFLOW_MEMORY_LIMIT_MBS.

You can also set organization-level defaults and per-workflow overrides via the Retool API — these take priority over the environment variable defaults. If a workflow is hitting limits unexpectedly, check whether organization-level or workflow-level limits have been configured. Refer to Configure code executor resource limits for details.

Why is my Loop block failing?

The Loop block requires its input to be an array. If the input is a string, number, or object, the loop fails immediately.

To fix this, verify that the data source connected to the Loop block returns an array. If the upstream block returns an object with a nested array, use a Code block to extract the array before passing it to the loop.

Example: extracting an array from a query result

If a resource query returns { "users": [...] }, extract the array in a Code block:

return queryBlock.data.users;

Then pass the Code block's output to the Loop block.

If iterations are completing but taking too long, check the iteration timeout in the Loop block's Settings. The default per-iteration timeout is 10 seconds, configurable up to 2 minutes. If individual iterations consistently exceed this limit, reduce the amount of work done per iteration.

Why is my scheduled workflow not running at the expected time?

Retool adds a small random delay to scheduled workflows to prevent many workflows from triggering at exactly the same time. A workflow scheduled to run every hour may start up to 6 minutes late. This behavior is intentional and does not indicate a problem.

If a workflow is consistently delayed beyond this range:

• Check whether the previous run has finished. Each scheduled workflow run must complete before the next one can start. If a run is slower than the scheduled interval, the next run waits. Open Run history to review recent run durations and confirm runs are completing before the next trigger fires.
• Confirm the interval meets the minimum. Scheduled workflows cannot run more frequently than once per minute.

To disable this delay on self-hosted instances, go to Settings > Beta and disable Enable jitter on cron Workflows.

Why is my workflow hitting the concurrency limit?

On cloud, no more than 100 runs of the same workflow can be active at the same time. Additionally, no more than 200 runs can be triggered within any 10-second window. When either limit is reached, new runs are blocked until an active run completes.

If your workflow is hitting these limits:

• Open Run history to check whether runs are completing quickly or getting stuck. Long-running runs reduce the available concurrency slots.
• Look for app-side logic that triggers the same workflow at high frequency. Consider batching or debouncing triggers to reduce the total number of runs.
• Optimize slow blocks—for example, replace sequential inserts with a bulk write operation.

On self-hosted instances, concurrency and burst limits are not enforced by default and can be configured using environment variables.

Why is my webhook timing out before returning a response?

Synchronous webhook-triggered workflows must reach the first Response block within 15 minutes. If no Response block is reached within that window, the caller receives a timeout error.

Common causes:

• Slow blocks (database queries, external API calls) are positioned before the Response block.
• The workflow has no Response block at all.

To fix this, move the Response block as early in the workflow as possible. Place all non-critical processing—notifications, logging, secondary writes—in blocks after the Response block. Those blocks execute asynchronously and do not delay the response.

Refer to Trigger workflows with webhooks for more on configuring webhook triggers and response behavior.

Why isn't my workflow running when triggered from a classic app?

If a classic app trigger isn't executing the workflow, check the following:

• The workflow must be published. Workflows only execute from app triggers when they are in a published state. Open the workflow and select Publish to deploy the latest version.
• Confirm the user has access. Users who do not have permission to access the workflow cannot trigger it. Check the workflow's permission settings and confirm the relevant groups or users are included.
• Understand async behavior. If the workflow has no Response block, it runs asynchronously—the app does not wait for the workflow to finish and receives no return value. If you need data returned to the app, add a Response block to the workflow.

Why is my block not retrying on failure?

Retry settings are configured per block in the block's Settings panel. The default behavior is to stop the workflow when a block fails, not to retry.

To enable retries:

1. Select Settings on the block.
2. Under On error, set the policy to Retry.
3. Configure the number of retry attempts (up to 9) and the interval between retries (up to 10 seconds).

For blocks that call rate-limited APIs, enable exponential backoff in the retry settings to space out attempts and reduce the chance of repeated failures.

Refer to Configure error handlers for a full overview of block-level and global error handling.

Why are my workflow run logs missing or incomplete?

Logs are not retained indefinitely. On cloud, run history is kept for 30 days by default, up to a maximum of 90 days. If you cannot find logs for a specific run, the retention period may have passed.

Admins can configure the retention period at Settings > Advanced settings > Workflows: Enable Data Retention.

Logs may be truncated on self-hosted instances. A single run can generate and store up to 10 MB of log data. If a run produces more than that, older entries within the run are truncated.

If you need to capture structured error data from runs, use a Code or resource query block configured as a global error handler to write errors to an external logging system. Refer to Workflow observability and error reporting for details on integrating with external services.

Why is my webhook URL alias invalid?

When setting a custom URL alias for a webhook trigger, keep the following rules in mind:

• The first segment of the path must be a static string. For example, /orders/{id} is valid, but /{id}/orders is not.
• Paths must not contain empty segments. Avoid double slashes (//) and trailing slashes.
• Each parameter name must be unique within a single path.
• Paths that are structurally identical but use different parameter names are not allowed (for example, /orders/{id} and /orders/{status} cannot both exist).

Refer to Trigger workflows with webhooks for guidance on configuring webhook aliases and path parameters.

Why is my workflow exceeding the outbound request limit?

Retool limits each workflow run to 50 in-flight outbound requests at one time. If your workflow fires more than 50 concurrent external calls, some requests fail.

To work around this limit:

• Use a Loop block to process requests sequentially rather than all at once.
• Split large parallel request batches into smaller groups and introduce a wait between batches.

On self-hosted instances, you can raise this limit using the WORKFLOW_REQUEST_CONCURRENCY_LIMIT environment variable.

Why can't I access my workflow?

If you receive an error when opening or running a workflow, check the following:

• Confirm the workflow exists. If the workflow was deleted or never saved, Retool returns a not found error.
• Check your permissions. If you do not have access to the workflow's folder or the workflow itself, Retool returns an authorization error.