shopify-debugging skill

---
name: shopify-debugging
description: Complete debugging and troubleshooting guide for Shopify including Liquid errors, theme preview debugging, API error handling, JavaScript console debugging, network request inspection, cart issues, checkout problems, and common error codes. Use when debugging Liquid syntax errors, troubleshooting theme rendering issues, fixing API errors, debugging JavaScript, investigating cart problems, or resolving webhook failures.
---

# Shopify Debugging & Troubleshooting

Expert guidance for debugging Shopify themes, apps, and API integrations with practical solutions to common issues.

## When to Use This Skill

Invoke this skill when:

- Debugging Liquid template errors or syntax issues
- Troubleshooting theme rendering problems
- Fixing API errors (GraphQL, REST)
- Debugging JavaScript errors in themes or apps
- Investigating cart or checkout issues
- Resolving webhook delivery failures
- Troubleshooting OAuth authentication problems
- Debugging theme preview or customizer issues
- Investigating slow page loads or performance problems
- Fixing metafield or metaobject access errors
- Resolving CORS or network request issues

## Core Capabilities

### 1. Liquid Debugging

Debug Liquid template errors and rendering issues.

**Enable Theme Preview:**
```
1. Go to Online Store > Themes
2. Click "Customize" on your theme
3. Open browser DevTools (F12)
4. Check Console for Liquid errors
```

**Common Liquid Errors:**

**Syntax Error:**
```liquid
{# ❌ Error: Missing endif #}
{% if product.available %}
  <button>Add to Cart</button>
{# Missing {% endif %} #}

{# ✅ Fixed #}
{% if product.available %}
  <button>Add to Cart</button>
{% endif %}
```

**Undefined Variable:**
```liquid
{# ❌ Error: product undefined on collection page #}
{{ product.title }}

{# ✅ Fixed: Check context #}
{% if product %}
  {{ product.title }}
{% else %}
  {# Not on product page #}
{% endif %}
```

**Invalid Filter:**
```liquid
{# ❌ Error: Unknown filter #}
{{ product.price | format_money }}

{# ✅ Fixed: Correct filter name #}
{{ product.price | money }}
```

**Debug Output:**
```liquid
{# Output variable as JSON #}
{{ product | json }}

{# Check variable type #}
{{ product.class }}

{# Check if variable exists #}
{% if product %}
  Product exists
{% else %}
  Product is nil
{% endif %}

{# Output all properties #}
<pre>{{ product | json }}</pre>
```

**Console Logging from Liquid:**
```liquid
<script>
  console.log('Product ID:', {{ product.id }});
  console.log('Product data:', {{ product | json }});
  console.log('Cart:', {{ cart | json }});
</script>
```

### 2. JavaScript Debugging

Debug JavaScript errors in themes and apps.

**Browser Console:**
```javascript
// Log to console
console.log('Debug:', variable);
console.error('Error:', error);
console.warn('Warning:', warning);

// Log object properties
console.table(data);

// Group related logs
console.group('Cart Operations');
console.log('Cart ID:', cartId);
console.log('Items:', items);
console.groupEnd();

// Time operations
console.time('API Call');
await fetch('/api/data');
console.timeEnd('API Call');

// Stack trace
console.trace('Execution path');
```

**Breakpoints:**
```javascript
// Programmatic breakpoint
debugger;

// Set in browser DevTools:
// Sources tab > Click line number
```

**Error Handling:**
```javascript
// ❌ Unhandled error
const data = await fetch('/api/data').then(r => r.json());

// ✅ Proper error handling
try {
  const response = await fetch('/api/data');

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  const data = await response.json();
  console.log('Data:', data);
} catch (error) {
  console.error('Failed to fetch data:', error);
  // Show user-friendly error message
  alert('Failed to load data. Please try again.');
}
```

**Network Debugging:**
```
1. Open DevTools > Network tab
2. Filter by XHR or Fetch
3. Click request to see:
   - Request headers
   - Request payload
   - Response headers
   - Response body
   - Timing information
```

### 3. API Error Debugging

Debug GraphQL and REST API errors.

**GraphQL Errors:**

Error response format:
```json
{
  "errors": [
    {
      "message": "Field 'invalidField' doesn't exist on type 'Product'",
      "locations": [{ "line": 3, "column": 5 }],
      "path": ["product", "invalidField"],
      "extensions": {
        "code": "FIELD_NOT_FOUND",
        "typeName": "Product"
      }
    }
  ],
  "data": null
}
```

**Check for errors BEFORE accessing data:**
```javascript
const response = await fetch(graphqlEndpoint, {
  method: 'POST',
  headers: {
    'X-Shopify-Access-Token': accessToken,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query, variables }),
});

const { data, errors } = await response.json();

// ✅ Always check errors first
if (errors) {
  console.error('GraphQL Errors:');
  errors.forEach(error => {
    console.error('Message:', error.message);
    console.error('Location:', error.locations);
    console.error('Path:', error.path);
    console.error('Code:', error.extensions?.code);
  });
  throw new Error(errors[0].message);
}

// Now safe to use data
console.log('Products:', data.products);
```

**Common GraphQL Errors:**

**Authentication Error:**
```json
{
  "errors": [{
    "message": "Access denied",
    "extensions": { "code": "UNAUTHENTICATED" }
  }]
}
```

**Fix:** Check access token:
```javascript
// Verify token is valid
const token = 'shpat_...';

// Check token format (should start with shpat_)
if (!token.startsWith('shpat_')) {
  console.error('Invalid token format');
}

// Verify in headers
headers: {
  'X-Shopify-Access-Token': token,  // ✅ Correct header
  'Authorization': `Bearer ${token}`, // ❌ Wrong for Admin API
}
```

**Field Not Found:**
```json
{
  "errors": [{
    "message": "Field 'invalidField' doesn't exist on type 'Product'"
  }]
}
```

**Fix:** Check field name in API docs:
```graphql
# ❌ Wrong field name
query {
  product(id: "gid://shopify/Product/123") {
    invalidField
  }
}

# ✅ Correct field name
query {
  product(id: "gid://shopify/Product/123") {
    title
    handle
    status
  }
}
```

**Rate Limit Error:**
```javascript
// Check rate limit header
const response = await fetch(graphqlEndpoint, options);

const rateLimit = response.headers.get('X-Shopify-GraphQL-Admin-Api-Call-Limit');
console.log('Rate limit:', rateLimit); // "42/50"

if (response.status === 429) {
  const retryAfter = response.headers.get('Retry-After');
  console.log(`Rate limited. Retry after ${retryAfter} seconds`);
}
```

**REST API Errors:**

**404 Not Found:**
```javascript
const response = await fetch(`https://${shop}/admin/api/2025-10/products/999999.json`, {
  headers: { 'X-Shopify-Access-Token': token },
});

if (response.status === 404) {
  console.error('Product not found');
  // Check:
  // 1. Product ID is correct
  // 2. Product exists in store
  // 3. Using correct endpoint
}
```

**422 Unprocessable Entity:**
```json
{
  "errors": {
    "title": ["can't be blank"],
    "price": ["must be greater than 0"]
  }
}
```

**Fix:** Validate input:
```javascript
const response = await fetch(endpoint, {
  method: 'POST',
  headers: {
    'X-Shopify-Access-Token': token,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    product: {
      title: '',  // ❌ Empty title
      price: -10, // ❌ Negative price
    },
  }),
});

if (response.status === 422) {
  const { errors } = await response.json();
  console.error('Validation errors:', errors);

  // Fix data
  const validProduct = {
    title: 'Product Name',  // ✅ Valid title
    price: 19.99,           // ✅ Valid price
  };
}
```

### 4. Cart Debugging

Debug cart and Ajax API issues.

**Cart Not Updating:**
```javascript
// ❌ Common mistake: Wrong variant ID
fetch('/cart/add.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: '123',  // ❌ Wrong: using product ID instead of variant ID
    quantity: 1,
  }),
});

// ✅ Fixed: Use variant ID
fetch('/cart/add.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: 123456789,  // ✅ Variant ID (numeric)
    quantity: 1,
  }),
})
  .then(response => {
    if (!response.ok) {
      return response.json().then(err => {
        console.error('Cart error:', err);
        throw err;
      });
    }
    return response.json();
  })
  .then(item => {
    console.log('Added to cart:', item);
    // Update cart UI
  })
  .catch(error => {
    console.error('Failed to add to cart:', error);
  });
```

**Get Current Cart:**
```javascript
// Debug current cart state
fetch('/cart.js')
  .then(r => r.json())
  .then(cart => {
    console.log('Cart:', cart);
    console.log('Item count:', cart.item_count);
    console.log('Total:', cart.total_price);
    console.log('Items:', cart.items);

    cart.items.forEach(item => {
      console.log('Item:', item.product_id, item.variant_id, item.quantity);
    });
  });
```

**Cart AJAX Errors:**
```javascript
// Common error: Insufficient inventory
{
  "status": 422,
  "message": "You can only add 5 of this item to your cart",
  "description": "Cannot add more than 5 to cart"
}

// Fix: Check inventory before adding
const variant = product.variants.find(v => v.id === variantId);

if (variant.inventory_quantity < quantity) {
  alert(`Only ${variant.inventory_quantity} available`);
} else {
  // Add to cart
}
```

### 5. Theme Preview Debugging

Debug issues in the theme customizer.

**Theme Editor Console:**
```
1. Open theme customizer
2. Open DevTools (F12)
3. Check Console for errors
4. Look for:
   - Liquid errors (red text)
   - JavaScript errors
   - Network failures
```

**Section Not Rendering:**
```liquid
{# Check section schema #}
{% schema %}
{
  "name": "My Section",
  "settings": [...]  {# ✅ Must have settings #}
}
{% endschema %}

{# ❌ Missing schema = won't show in customizer #}
```

**Settings Not Updating:**
```liquid
{# ❌ Wrong: Using hardcoded value #}
<h1>Hardcoded Title</h1>

{# ✅ Fixed: Use setting #}
<h1>{{ section.settings.title }}</h1>

{% schema %}
{
  "name": "Hero",
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Title",
      "default": "Welcome"
    }
  ]
}
{% endschema %}
```

**Block Attributes Missing:**
```liquid
{# ❌ Missing shopify_attributes #}
<div class="block">
  {{ block.settings.text }}
</div>

{# ✅ Fixed: Add shopify_attributes for theme editor #}
<div class="block" {{ block.shopify_attributes }}>
  {{ block.settings.text }}
</div>
```

### 6. Webhook Debugging

Debug webhook delivery and processing.

**Webhook Not Received:**

Check in Shopify Admin:
```
1. Settings > Notifications > Webhooks
2. Click webhook
3. Check "Recent deliveries"
4. Look for delivery status:
   - ✅ Success (200 OK)
   - ❌ Failed (4xx/5xx errors)
```

**Verify Webhook HMAC:**
```javascript
import crypto from 'crypto';

function verifyWebhook(body, hmac, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('base64');

  return hash === hmac;
}

// Express example
app.post('/webhooks/orders', (req, res) => {
  const hmac = req.headers['x-shopify-hmac-sha256'];
  const body = JSON.stringify(req.body);

  if (!verifyWebhook(body, hmac, process.env.SHOPIFY_WEBHOOK_SECRET)) {
    console.error('Invalid webhook HMAC');
    return res.status(401).send('Unauthorized');
  }

  console.log('Webhook verified');

  // Process webhook
  const order = req.body;
  console.log('Order:', order.id, order.email);

  // Respond quickly (< 5 seconds)
  res.status(200).send('OK');
});
```

**Webhook Timeout:**
```javascript
// ❌ Processing takes too long (> 5 seconds)
app.post('/webhooks/orders', async (req, res) => {
  await processOrder(req.body);  // Slow operation
  res.send('OK');  // Response delayed
});

// ✅ Respond immediately, process async
app.post('/webhooks/orders', async (req, res) => {
  const order = req.body;

  // Respond quickly
  res.status(200).send('OK');

  // Process in background
  processOrder(order).catch(console.error);
});
```

### 7. Common Error Messages

**Liquid Errors:**

```
Error: Liquid syntax error: Unknown tag 'section'
Fix: Use {% section %} only in JSON templates, not .liquid files
```

```
Error: undefined method 'title' for nil:NilClass
Fix: Variable is nil. Add {% if %} check or provide default:
{{ product.title | default: "No title" }}
```

```
Error: Exceeded maximum number of allowed iterations
Fix: Infinite loop detected. Check loop conditions.
```

**JavaScript Errors:**

```
TypeError: Cannot read property 'forEach' of undefined
Fix: Array is undefined. Check:
if (items && Array.isArray(items)) {
  items.forEach(item => { ... });
}
```

```
ReferenceError: $ is not defined
Fix: jQuery not loaded or script runs before jQuery loads
```

```
SyntaxError: Unexpected token <
Fix: API returned HTML error page instead of JSON. Check API endpoint.
```

**API Errors:**

```
Access denied - check your access scopes
Fix: App needs additional permissions. Update scopes in Partner Dashboard.
```

```
Throttled: Exceeded API rate limit
Fix: Implement rate limit handling with exponential backoff.
```

```
Field doesn't exist on type
Fix: Check API version and field availability in docs.
```

## Debugging Toolkit

**Browser DevTools:**
```
- Console: View errors and logs
- Network: Inspect API requests
- Sources: Set breakpoints
- Application: View cookies, localStorage
- Performance: Profile page load
```

**Shopify Tools:**
```
- Theme Preview: Test changes before publishing
- Theme Inspector: View section data
- API Explorer: Test GraphQL queries
- Webhook Logs: Check delivery status
```

**Useful Console Commands:**
```javascript
// Get all form data
new FormData(document.querySelector('form'))

// View all cookies
document.cookie

// Check localStorage
localStorage

// View all global variables
console.log(window)

// Get computed styles
getComputedStyle(element)
```

## Best Practices

1. **Always check for errors** before accessing data (API responses)
2. **Use try-catch blocks** for all async operations
3. **Log meaningful messages** with context
4. **Verify HMAC** for all webhooks
5. **Test in theme preview** before publishing
6. **Monitor API rate limits** and implement backoff
7. **Handle edge cases** (nil values, empty arrays)
8. **Use browser DevTools** for network debugging
9. **Check API version** compatibility
10. **Validate input** before API calls

## Integration with Other Skills

- **shopify-liquid** - Use when debugging Liquid template code
- **shopify-api** - Use when debugging API calls
- **shopify-theme-dev** - Use when debugging theme structure issues
- **shopify-app-dev** - Use when debugging custom apps
- **shopify-performance** - Use when debugging slow performance

## Quick Reference

```javascript
// Debug Liquid
{{ variable | json }}
{% if variable %}{{ variable }}{% endif %}

// Debug JavaScript
console.log('Debug:', data);
debugger;

// Debug API
const { data, errors } = await response.json();
if (errors) console.error(errors);

// Debug Cart
fetch('/cart.js').then(r => r.json()).then(console.log);

// Debug Webhooks
const valid = verifyHmac(body, hmac, secret);
console.log('Webhook valid:', valid);
```