| name | shopify-advanced-troubleshooting |
| description | Debug complex Shopify API issues using cost analysis, request tracing,
webhook delivery inspection, and GraphQL introspection.
Use when encountering intermittent failures, throttling mysteries, or webhook delivery gaps.
Trigger with phrases like "shopify hard bug", "shopify mystery error",
"shopify deep debug", "difficult shopify issue", "shopify intermittent failure".
|
| allowed-tools | Read, Grep, Bash(curl:*), Bash(node:*) |
| version | 2.7.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","ecommerce","shopify"] |
| compatibility | Designed for Claude Code |
Shopify Advanced Troubleshooting
Overview
Deep debugging for complex Shopify API issues: cost analysis with debug headers, webhook delivery inspection, GraphQL query introspection, and systematic isolation of intermittent failures.
Prerequisites
- Access to Shopify admin and Partner Dashboard
- Familiarity with GraphQL and HTTP debugging
curl and jq available
Instructions
Step 1: GraphQL Cost Analysis
When queries THROTTLE unexpectedly, use the cost debug header by adding Shopify-GraphQL-Cost-Debug: 1 to your request. The response extensions.cost reveals why a query is expensive.
Key: requestedQueryCost is first multiplied through nested connections. 50 products * 20 variants * (1 + 5 metafields) = high cost even if actual data is small.
Step 2: Trace a Specific Request
Every Shopify response includes X-Request-Id. Capture it for support escalation:
curl -v -X POST "https://$STORE/admin/api/2025-04/graphql.json" \
-H "X-Shopify-Access-Token: $TOKEN" \
-H "Content-Type: application/json" \
-d '{"query": "{ shop { name } }"}' 2>&1 | tee /tmp/shopify-debug.txt
grep -i "x-request-id" /tmp/shopify-debug.txt
Step 3: Webhook Delivery Inspection
Inspect webhook delivery status in the Partner Dashboard, or query subscription health via API.
See Webhook Status Query for the complete query and common delivery failure patterns.
Step 4: GraphQL Introspection for API Version Differences
Use introspection queries to check if specific fields or mutations exist in your API version. Query __type for field lists or __schema for available mutations filtered by prefix.
Step 5: Systematic Isolation
Run a layer-by-layer diagnostic that tests DNS, TCP, TLS, HTTP, GraphQL, and rate limit state independently.
See Layer-by-Layer Diagnostic for the complete shell script.
