Troubleshooting

Connection fails

Check that ShopMCP is installed, the connection is active, and Shopify OAuth is complete. If access was revoked, reconnect the client.

Access is denied

Check the connection, its resource permissions, Shopify app scopes, and the staff account. Enabling a skill does not grant permission.

A skill does not appear

Check that it is enabled for this specific connection and that the client can retrieve ShopMCP skill tools. Refresh the connection in the client.

Results are incomplete

Follow every list's pagination until hasNextPage is false. Nested results can have their own cursors. The client should show missing pages instead of assuming the results are complete.

Inventory returns CHANGE_FROM_QUANTITY_STALE

Shopify did not find the expected starting inventory quantity. Read the current quantity and compare it with the desired value before taking action. Do not reuse the old comparison value or simply write again with a new idempotency key. If the target quantity is already set, no further change is needed; otherwise plan a new operation using the freshly read state. Shopify documents successful retries of the same idempotent request within 24 hours as cached responses. If an identical replay after a successful first request instead returns CHANGE_FROM_QUANTITY_STALE, this is an unresolved API discrepancy: check the current quantity and do not count the replay as success.

A shipping tool or update does not match the store

ShopMCP chooses the shipping path based on Shopify's marketDrivenShipping feature. Without the preview feature, the legacy Delivery Profiles apply; with the feature, Market-driven Shipping and its required Market scopes apply. A successful API response does not automatically prove the rate appears at checkout. Use an eligible test shop for preview changes, then test checkout.

Report a ShopMCP issue

An AI client can read get_support_reporting_instructions to learn the reporting workflow. It prepares a short technical report in the conversation, shows it to you, and asks whether it may submit the report with the shop domain and connection ID. Only after you agree does it call submit_support_report. No automatic reports, raw tool data, or conversation history are sent. See [Report an issue](/docs/support?locale=en). If the connection is completely unavailable, contact support@shopmcp.app manually.