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.
On this page
Errors when editing workflows
When you're editing a workflow, you might encounter errors that prevent you from saving the workflow. The following are common errors that you might encounter when editing a workflow:
Data not found
When adding a new action to a workflow, you might encounter an error that says Data not found
, for example, Customer data not found
. This error occurs when the data required for the action isn't available. For example, if you're adding an action that requires a product ID, then this error means that your workflow hasn't supplied a usable product.
Typically, this data is provided by a trigger or a "Get data" action. If using "Get data", then a common issue is that the action requires a single item (the customer) but the action provides a list (a list of customers). To call the action you must add a For each action to loop over the list and call the action for each item in the list.
For issues with trigger data, consult the documentation for your action to find a trigger that provides the right data.
Errors when a workflow runs
When a workflow run encounters an error, the workflow run is marked as failed. The error message is displayed in the workflow run details. The following are common errors that you might encounter when a workflow run fails:
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.
Fields: id are required but are empty
Most Shopify actions require one or more resources (such as a product, customer, or order) to run. Sometimes the resource isn't available, so the action cannot run as intended. For example, it is possible to create an order in the Admin that does not have a customer. If you attempt to run an action, such as Add customer tags, then the action will fail with this error.
To prevent an error, you can add a Condition before the action to check if the resource exists. In the previous example, if you wanted to send an internal email in the same workflow as Add customer tags, then you can either put the action before the step that can fail, or you can do one of the following.
Put the actions in parallel branches (where two or more branches come out of a step)
![Example showing two actions in parallel](https://cdn.shopify.com/shopifycloud/help/assets/manual/apps/flow/flowv2/error-example-parallel-611c70be32f76c4eb94026b2cda5a11798d47a50eb6a4a2729f845e813dd1a49.png)
Add a condition before the action to check if the customer is present. For example, you can check if order / customer / id is not empty and exists
.
![Example showing a condition looking for an ID](https://cdn.shopify.com/shopifycloud/help/assets/manual/apps/flow/flowv2/error-example-check-nil-9617efec593c595b0bcc6a76daa5d87a63eb59045f0731a6e6a98c1e5ca788c1.png)
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, then 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:
- Get Shopify alert when workflow run errors are detected
- Get notified by email when workflow run errors are detected
- Get Slack notification when workflow run errors are detected
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.
Running (rate limited)
In some cases, a workflow or workflows can use too many resources, and in order to prevent this from causing problems Flow will intentionally limit the execution of runs on your store, which might cause delays and timeout errors. This can be fixed by re-writing inefficient workflows, usually to fix a bug where it wasn't functioning as intended.
Running for too long
This message indicates that runs for a workflow are taking a very long time to execute. This is commonly caused by using a large amount of data within a workflow that takes Flow a lot of time to fetch.
Example
These cases are commonly caused by deep request paths that go through multiple lists of items (such as requesting all metafields for all products in all collections that a product is a part of):
![long running workflow example](https://cdn.shopify.com/shopifycloud/help/assets/manual/shopify-flow/long-running-workflow-example-c533be66e2d0218f9fe7caf173c16ae7e47f366dc955ba25f4b2c36a5f267ef2.png)
Workflows that loop through all metafields can often be improved by only using a specific metafield. Accessing multiple nested lists (such as all products on all collections for a product) or particularly large lists (such as metafield definitions, which contains all metafields for all objects) might have been done unintentionally, and selecting the correct field (the single product or a single metafield on an object) can significantly improve efficiency. In other cases, using a "Get Product/Order/Customer Data" action with a query filter can significantly reduce the number of objects used but still accessing the relevant ones.
Processing too much data
This message indicates that runs for a workflow are generating a large amount of data. This is commonly caused by having complex conditions that check many fields, usually due to checking fields on multiple layers of lists.
Example
For example, a condition such as "For at least one tag on this customer, for at least one order line items, for at least one tag on the line item" can result in many checks being performed, and a lot of data being generated to display the results of those checks:
![too much data workflow example](https://cdn.shopify.com/shopifycloud/help/assets/manual/shopify-flow/too-much-data-workflow-example-63617573b64bc89b2a45ce9a400dbec50e92d6b1870561caee149592e60be5a3.png)
Automatic retries failing
This message indicates that runs for a workflow are repeatedly failing due to some temporary issue but that they're not frequently succeeding on subsequent retries. This often occurs when either Shopify's Admin API or a partner's app is encountering a high volume of requests.