Troubleshoot the Openflow Connector for Shopify

Note

This connector is subject to the Snowflake Connector Terms.

This topic describes how to troubleshoot the Openflow Connector for Shopify.

A table never appears or is empty

  1. Confirm the apiType is listed in the Objects to Sync parameter and spelled correctly (matching is case-insensitive, but the value must correspond to a query root in the Shopify Admin GraphQL API).
  2. Confirm the custom app has the matching read scope for that object type. For example, orders requires read_orders. A missing scope produces access errors or empty results for that object type only, without affecting other objects.
  3. If you’re using a custom object definition, confirm the Object Definitions Override value is valid JSON and a top-level array, then re-enable the controller services.
  4. If you’re relying on auto-discovery, confirm Enable Introspection is set to true.

A query fails with an access-denied error on one field

Some Shopify Admin GraphQL fields require a write scope to be read. For example, the customer marketing URL fields (marketingUnsubscribeUrl, openTrackingUrl) require write_customers. When the access token lacks the required scope, the Shopify API returns an error for that field and the entire object’s query fails.

The fix is to remove the field from the query rather than grant a write scope:

  • Top-level field (a direct entry in graphqlFields): remove it from graphqlFields, or add its name to ignoredFields.
  • Nested field (inside a sub-selection, for example marketingUnsubscribeUrl inside defaultEmailAddress { ... }): ignoredFields only matches the leading name of top-level entries and doesn’t apply to nested sub-selections. Edit the parent entry’s sub-selection in graphqlFields to remove the offending field.

Supply the corrected definition through the Object Definitions Override parameter. For more information, see Object definition overrides for the Openflow Connector for Shopify.

Orders are missing older history (only approximately 60 days present)

The read_orders scope limits access to orders created in the last 60 days by default. To backfill the full order history, the custom app must also be granted read_all_orders. This scope requires a Partner Dashboard access request from Shopify.

After granting read_all_orders, reset the orders object state so the bulk load reruns and captures the full history.

Connector won’t start or Object Registry service is INVALID

This is almost always caused by an invalid Object Definitions Override value. The value must be syntactically valid JSON and a top-level array. An invalid value or a non-array value prevents the StandardShopifyObjectRegistryService from enabling, and the connector fails to start.

To diagnose:

  1. Open the Controller Services panel and select the StandardShopifyObjectRegistryService.
  2. Check the service bulletin for the parse error, such as “Invalid JSON” or “Must be a JSON array of object definitions”.
  3. Fix the JSON, re-apply the parameter, and re-enable the service.

You can validate the JSON before applying it:

python3 -c "import json, sys; d = json.load(open('override.json')); sys.exit(0 if isinstance(d, list) else 1)"

Bulk operation fails immediately

The following scenarios can cause a bulk operation to fail immediately or stall.

Wrong sort key

An unsupported value in sortKeys fails the entire bulk operation. Remove the sort key from the object definition or correct it. Omitting sortKeys is always safe.

Bulk operation already in progress

Shopify allows only one bulk operation per shop at a time. The processor retries automatically on the next cycle. If the in-flight operation never clears, another integration on the same shop may be holding the bulk slot.

Too many or too deeply nested connections

The Shopify Bulk Operations API allows a maximum of 5 connections per query and 2 levels of nesting. If Include Metafields is enabled, it consumes one connection. Reduce or flatten child connections to stay within these limits.

Bulk operation stuck with no progress

Very large datasets can take significant time to complete. If a bulk operation shows no progress after an extended period, it may be stalled. Check the Shopify admin for the status of the bulk operation, or reset the affected object to resubmit.

Duplicate or missing records in Snowflake

Duplicates immediately after the initial load are expected during the bulk-to-incremental handoff. The merge uses the compound key (ID, SHOP_URL), so the target table converges after the first incremental run. No action is required.

Records missing or not updating: The incremental watermark may have advanced past the affected records. Inspect the per-object state to check the high watermark. If the watermark is incorrect, reset the object to rerun the bulk load.

For orders specifically, also confirm that the 60-day order history window isn’t the cause. For more information, see Orders are missing older history.

Incremental processor routes to retry or failure on first run

The GetShopifyIncremental processor routes to retry or failure until the one-time bulk load for each object type completes. This is expected behavior on the first run. Let the bulk load finish before investigating further.

Incremental fails with “Invalid search field: <name>”

This error appears in the GetShopifyIncremental bulletin when the object’s incrementalField exists on the returned type but isn’t accepted as a filter by the query root’s query: argument.

Fix: in the object’s Object Definitions Override entry, set supportsIncremental to false and refreshStrategy to FULL_PERIODIC. The object will perform a bulk load once and won’t poll incrementally. To refresh it, reset the object state.

Common objects affected: codeDiscountNodes, automaticDiscountNodes. For discount syncing with incremental support, use the discountNodes query root instead.

After editing the override JSON, re-enable the StandardShopifyObjectRegistryService.

Schema changed in Shopify

Schema evolution isn’t supported. If a Shopify object’s fields change (fields added or removed), reset the connector state for the affected object and drop the corresponding Snowflake table to re-snapshot with the updated schema.

Deletes aren’t appearing in Snowflake

Check the following in order:

  1. The object type must support delete detection. Only object types that emit destroy events in the Shopify Events API can be tracked. For more information, see How deletes are handled.
  2. The object type must be listed in the Objects to Track for Deletes parameter.
  3. The initial bulk load for that object type must be complete before delete polling begins.
  4. Delete events younger than the safety buffer (default 5 minutes) are intentionally deferred.
  5. Delete polling yields when API credits fall below the rate limit threshold (default 500 points). Check the processor bulletin for messages indicating the connector is below the rate limit threshold and yielding.

Error: “first cannot exceed 250”

This error occurs when a regular (incremental) query sets first: above Shopify’s hard limit of 250. The full error is: “first cannot exceed 250. To query larger amounts of data with fewer limits, bulk operations should be used instead.”

Check the Page Size parameter and the pageSize value in any childFields definitions in the Object Definitions Override. Both must be 250 or lower.

Note that this limit doesn’t apply to the initial bulk load: the Shopify Bulk Operations API ignores the first: argument and returns all records. For parent objects with more children than the pageSize value, only the initial bulk load captures the full child set; incremental runs are capped at pageSize per parent.

Sustained throttling

High-volume stores with many objects can remain rate-limited for extended periods. To reduce API usage:

  • Increase the Sync Schedule and Deletes Schedule intervals.
  • Reduce the number of entries in Objects to Sync.
  • Disable Include Metafields if metafield data isn’t required.

StandardPrivateKeyService shows INVALID on SPCS or SNOWFLAKE_MANAGED deployments

The StandardPrivateKeyService controller is only used for BYOC deployments with KEY_PAIR authentication. On SPCS deployments, and on BYOC deployments using SNOWFLAKE_MANAGED authentication, this controller is unused and may display an INVALID status.

This is expected behavior and has no impact on the connector. The connector works correctly regardless of this controller’s status. Deleting the controller causes local modifications to the flow definition, so Snowflake recommends leaving it in place.