Troubleshooting Flow errors and usage limits

This document describes common errors and limits, why they occur, and how to resolve them. There are two types of errors that you might encounter in Flow, permanent errors and transient errors.

Transient errors

Transient errors are temporary errors that occur when Flow is unable to complete a task. These errors are retried until they either succeed or reach a timeout limit. For example, if Flow is unable to contact a partner when executing a connector action, then Flow retries the task multiple times before giving up.

Retries are spread out, with the delay between each subsequent attempt increasing from the previous delay. Typically, when a workflow experiences transient errors, it remains in the running state for a long time as it retries tasks.

When a task is retried successfully, then the workflow continues. If a retried task experiences a permanent error, then the workflow fails. Every workflow section has a combined upper execution limit of 36 hours. If a step with transient errors doesn't succeed before that limit is hit, then the workflow fails.

Workflows with wait steps are divided into sections, which affects how timeout limits are calculated in a workflow. Each section is a group of tasks that are executed together, and each has its own 36 hour time limit. For example, if a workflow has a wait step that waits for one hour, then the tasks before the wait step will be executed together in one section and the tasks after the wait step will be executed together in another section. If a workflow has multiple wait steps, then the tasks between each wait step will be executed together in one section. Workflows without a wait step are considered one section.

Occasional transient errors are common. However, if you have a workflow that consistently encounters the same transient error across multiple runs, then your workflow might need to be reconfigured.

Step timed out

Step timed out errors typically occur when a task in the workflow attempts to query too much data in one section. This error frequently occurs in workflows that iterate over lists, particularly nested lists, that are too large to fetch in a timely manner.

When a workflow encounters this error, the trigger or wait step is displayed as retrying.

To resolve this, check any conditions that access lists and nested lists to ensure they're correct. A common problem is that a condition checks all products on a shop rather than just the products in an order.

5xx status

Most Flow actions involve making HTTP calls. Occasionally, networking or other server issues can cause HTTP calls to fail and return an error code between 500 and 599. Seeing one occurrence of this error isn't an issue, but repeated instances might indicate an issue with the server handling the task, rather than how the step is configured.

This type of error is most commonly displayed on the Send HTTP Request action, but it can happen on most tasks.

GraphQL Throttled

The total volume of work done by a workflow is limited by API rate limits, which are determined in part by your plan. Typically, these limits aren't reached unless a workflow is very complex or has an unintentional design error. The following are examples of scenarios that can lead to this error:

Liquid or conditions in the workflow loop over a list with large amounts of data, such as checking metafield values that contain HTML.
Liquid or conditions in the workflow loop over a large list, such as looping over shop.orders in a large shop.
A workflow results in an infinite loop in which the workflow keeps creating new workflow runs. For example, this can happen if the workflow uses the Customer tags added trigger and includes the Add customer tags action.

If the limit is reached, then you receive a GraphQL throttled error. This error can affect other workflows when they attempt to run, so this error should be resolved immediately if it occurs.

Permanent errors

Permanent errors are errors that occur when Flow is unable to complete a task, and the task cannot be retried. For example, if Flow is unable to send an email because the email address is invalid, then it doesn't retry the task. Instead, the workflow fails.

Flow does not have permission to your Google Sheets account. Please reconnect your account.

The Google Sheets connector requires you to link your Google account to Flow to have permission to write to the sheet. This error can occur when Flow doesn't have permission to write to a sheet, either because the account was unlinked from Flow or because that account isn't able to access that sheet.

To resolve this, ensure the account being used for the connector can open the sheet and has edit access. If the wrong account is linked, then you can disconnect it and connect a new one.

Steps:

Open or create a new workflow.
Add an action.
Select the Google Sheets connector.
Click Disconnect, and then click Connect.

Flow action received with invalid properties. Customer does not accept marketing.

The Send marketing email action doesn't send emails to customers who haven't agreed to receive them, and permanently fails if the workflow attempts to do so.

To resolve this, add a condition in the workflow that checks the customers subscription status. You can ensure that customers have agreed to receive marketing emails before sending them. Follow the steps in Email subscriber list management.

Missing resource for [resource type]

This error indicates that a resource, such as customer or order, was deleted before the workflow was able to fetch its data. Most often this occurs after a wait step, but it's possible for this happen on the trigger as well if the resource is deleted very quickly after the trigger event happens.

Get notified when an error occurs

If having errors will impact your store operations you can set up notifications for when an error occurs. Error notifications can be built like any other workflow using the Workflow error occurred trigger. Error notifications are designed to limit noise, so you will only get one notification per workflow version.

To get started, you can use one of the following templates:

Retrying runs

In some cases, a workflow run can encounter an error or not run as intended. After troubleshooting and fixing the issues in the related workflow, past runs can be manually retried to retroactively fix the result of past runs. Learn more about retrying workflow runs.