About

Imported from jeremylongshore/tons-of-skills-marketplace (plugins/saas-packs/shopify-pack/skills/shopify-advanced-troubleshooting/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill shopify-advanced-troubleshooting. Copyright stays with the author (MIT).

Shopify Advanced Troubleshooting

Name: shopify-advanced-troubleshooting
Author: jeremylongshore

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.

Step 6: Debug Intermittent Failures

Wrap Shopify calls in a debug logger that captures timing, cost, and error data for pattern analysis.

See Debug Intermittent Failures for the complete TypeScript implementation.

Output

Query cost breakdown identifying expensive fields
Request IDs captured for Shopify support
Webhook delivery health verified
Layer-by-layer isolation identifying failure point
Debug log with timing patterns for intermittent issues

Error Handling

Issue	Root Cause Pattern	Solution
Random THROTTLED errors	`requestedQueryCost` spikes on specific queries	Reduce `first:` and nested depth
Webhooks stop arriving	SSL certificate expired	Renew cert, check webhook subscriptions
502 errors on GraphQL	Shopify infrastructure blip	Retry with backoff, capture X-Request-Id
Slow responses (> 5s)	Complex query with metafields	Remove `metafields` or reduce page size
Data inconsistency	Race condition between webhook and query	Use `updatedAt` filter, add idempotency

Examples

Diagnosing Intermittent 502 Errors

A store experiences random 502 errors on product sync queries. Use the debug wrapper to capture timing and cost data across 100 requests, then analyze the pattern.

See Debug Intermittent Failures for the complete TypeScript implementation.

Isolating a Webhook Delivery Gap

Orders are created but the fulfillment webhook never fires. Run the webhook status query to check subscription health and delivery success rates.

See Webhook Status Query for the complete query and common delivery failure patterns.

Pinpointing a Network Layer Failure

API calls fail sporadically from a specific server. Run the layer-by-layer diagnostic to test DNS, TCP, TLS, HTTP, and GraphQL independently.

See Layer-by-Layer Diagnostic for the complete shell script.

Resources

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/jeremylongshore-tons-of-skills-marketplace-shopify-advan-c6ebfa/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

jeremylongshore-tons-of-skills-marketplace-shopify-advan-c6ebfa.ocm.jsonjson

{
  "ocm": "1",
  "id": "jeremylongshore-tons-of-skills-marketplace-shopify-advan-c6ebfa",
  "kind": "skill",
  "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\".",
  "publisher": "jeremylongshore",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding",
      "customer_support"
    ],
    "tags": [
      "skill-md",
      "saas",
      "ecommerce",
      "shopify",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "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\"."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/jeremylongshore/tons-of-skills-marketplace",
      "path": "plugins/saas-packs/shopify-pack/skills/shopify-advanced-troubleshooting/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/jeremylongshore/tons-of-skills-marketplace/blob/HEAD/plugins/saas-packs/shopify-pack/skills/shopify-advanced-troubleshooting/SKILL.md",
      "key": "jeremylongshore/tons-of-skills-marketplace/plugins/saas-packs/shopify-pack/skills/shopify-advanced-troubleshooting/SKILL.md"
    },
    "compatibility": "Designed for Claude Code",
    "allowed_tools": [
      "Read,",
      "Grep,",
      "Bash(curl:*),",
      "Bash(node:*)"
    ],
    "license": "MIT"
  },
  "instructions": "# Shopify Advanced Troubleshooting\n\n## Overview\n\nDeep debugging for complex Shopify API issues: cost analysis with debug headers, webhook delivery inspection, GraphQL query introspection, and systematic isolation of intermittent failures.\n\n## Prerequisites\n\n- Access to Shopify admin and Partner Dashboard\n- Familiarity with GraphQL and HTTP debugging\n- `curl` and `jq` available\n\n## Instructions\n\n### Step 1: GraphQL Cost Analysis\n\nWhen 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 q",
  "cost": {
    "context_tokens": 1085
  }
}

Fetch it by URL: GET /api/v1/registry/jeremylongshore-tons-of-skills-marketplace-shopify-advan-c6ebfa/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.