Common Shopify Theme Bugs and How to Fix Them

Why Shopify Theme Bugs Happen

Even well-built Shopify themes develop bugs over time. The most common causes are app conflicts (multiple apps trying to modify the same part of the page), theme updates that overwrite customizations, custom code added without thorough testing, and browser differences in how CSS and JavaScript are interpreted. The good news is that most Shopify bugs fall into predictable categories, and the solutions are well-established. This guide covers the five most common bug types we encounter, what causes them, and how to fix them.

Bug #1: Cart Not Updating

Symptoms: Clicking 'Add to Cart' does nothing, the cart count does not update, quantity changes in the cart do not stick, or the cart page shows stale data. This is the most common Shopify bug we diagnose. It is almost always caused by JavaScript errors preventing the cart API from working correctly. The root cause is typically an app conflict where two apps both try to intercept the add-to-cart event, a JavaScript error in another part of the page that breaks execution before the cart code runs, or outdated theme JavaScript that does not match the current Shopify cart API.

Diagnosing Cart Issues

// Step 1: Open the browser console (F12 or Cmd+Opt+J)
// and check for JavaScript errors. Red errors are your clue.

// Step 2: Test the cart API directly in the console:
fetch('/cart.js')
  .then(res => res.json())
  .then(cart => console.log('Current cart:', cart))
  .catch(err => console.error('Cart API error:', err));

// Step 3: Try adding a product directly via the API:
fetch('/cart/add.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    items: [{ id: YOUR_VARIANT_ID, quantity: 1 }]
  })
})
.then(res => res.json())
.then(data => console.log('Add to cart result:', data))
.catch(err => console.error('Add to cart error:', err));

// If Step 3 works but the button does not, the issue is in
// the theme's JavaScript event handling, not the cart API.

Bug #2: Mobile Display Issues

Symptoms: Elements overlapping on mobile, text too small to read, buttons impossible to tap, horizontal scrolling on the page, or content extending beyond the screen width. Mobile bugs are the second most common issue and are usually caused by fixed pixel widths instead of responsive units, missing or incorrect viewport meta tags, CSS that was tested only on desktop, images without max-width constraints, and absolute positioning that does not account for smaller screens.

Common Mobile CSS Fixes

/* Fix: Horizontal scrollbar on mobile (almost always caused by
   an element wider than the viewport) */
html, body {
  overflow-x: hidden; /* Quick fix, but find the actual cause */
  max-width: 100vw;
}

/* Better fix: Find the offending element */
/* Add this temporarily to identify what is too wide: */
* {
  outline: 1px solid red !important;
}

/* Fix: Images breaking out of containers */
img {
  max-width: 100%;
  height: auto;
}

/* Fix: Text too small on mobile */
/* Ensure your viewport meta tag is correct in theme.liquid: */
/* <meta name="viewport" content="width=device-width, initial-scale=1"> */

/* Fix: Tap targets too small (Google recommends 48x48px minimum) */
.button, a.link {
  min-height: 48px;
  min-width: 48px;
  padding: 12px 16px;
}

/* Fix: Fixed-width elements breaking mobile layout */
.problematic-element {
  /* Instead of: width: 600px; */
  width: 100%;
  max-width: 600px;
}

Bug #3: App Conflicts

Symptoms: Features that used to work suddenly stop after installing a new app. Visual glitches appear only on pages where a specific app is active. JavaScript console shows errors from multiple script sources. App conflicts happen because Shopify apps inject their own JavaScript and CSS into your storefront, and multiple apps may try to modify the same DOM elements. A reviews app and a recently-viewed app might both try to insert content below the Add to Cart button, causing layout breaks. The systematic debugging approach is to identify which apps are active on the affected page, disable them one at a time, and test after each change. Once you identify the conflicting pair, you have three options: contact one of the app developers for a fix, adjust the app settings to avoid the collision (different placement, different trigger), or hire a developer to write a compatibility patch.

Bug #4: Slow Loading Pages

Symptoms: Pages take more than 3 seconds to load, images load visibly slow, the page feels sluggish when scrolling or interacting, and Google PageSpeed gives a low score. Slow loading is technically a performance issue rather than a bug, but store owners experience it as something being 'broken.' The usual causes are unoptimized images (the number one culprit), too many installed apps loading JavaScript, render-blocking resources in the theme head, unminified CSS and JavaScript files, and excessive use of Liquid loops that slow server-side rendering.

Quick Performance Fixes

{%- comment -%} Fix: Serve properly sized images instead of full-resolution {%- endcomment -%}
{%- comment -%} Before (bad): {%- endcomment -%}
{%- comment -%} <img src="{{ image.src }}"> {%- endcomment -%}

{%- comment -%} After (good): Use image_url with width parameter {%- endcomment -%}
{{ image | image_url: width: 800 | image_tag: loading: 'lazy' }}

{%- comment -%} Fix: Defer non-critical app scripts {%- endcomment -%}
{%- comment -%} Before (bad): {%- endcomment -%}
{%- comment -%} <script src="app-script.js"></script> {%- endcomment -%}

{%- comment -%} After (good): {%- endcomment -%}
<script src="app-script.js" defer></script>

{%- comment -%} Fix: Preload critical resources {%- endcomment -%}
{%- comment -%} Add to theme.liquid <head>: {%- endcomment -%}
<link rel="preload" as="image" href="{{ section.settings.hero_image | image_url: width: 1200 }}">

Bug #5: Broken Collection Filters and Search

Symptoms: Filter options do not narrow results, search returns no results or irrelevant results, filter counts are wrong, URL parameters are not applied correctly, or the page reloads fully instead of updating dynamically. Shopify's native filtering (Storefront Filtering) works through URL parameters and the filter Liquid object. Bugs typically stem from themes that use legacy JavaScript-based filtering instead of Shopify's native approach, apps that interfere with the URL parameters, custom code that breaks the filter form submission, or missing filter settings in the theme's collection template. For native Shopify filtering issues, verify that your collection template includes the correct filter form markup and that your theme's JavaScript properly handles filter parameter changes. For app-based filtering solutions, contact the app developer since these are self-contained systems with their own debugging process.

Debugging Shopify Native Filters

{%- comment -%}
  Check if filters are available on your collection page.
  Add this temporarily to see what Shopify provides:
{%- endcomment -%}

{%- for filter in collection.filters -%}
  <div style="background: #f0f0f0; padding: 10px; margin: 5px 0;">
    <strong>{{ filter.label }}</strong> ({{ filter.type }})
    <br>Active values: {{ filter.active_values.size }}
    <br>Total values: {{ filter.values.size }}
    {%- for value in filter.values -%}
      <br>&nbsp;&nbsp;- {{ value.label }}
        ({{ value.count }} products)
        {%- if value.active %} [ACTIVE]{% endif -%}
    {%- endfor -%}
  </div>
{%- endfor -%}

{%- comment -%}
  If no filters appear, check:
  1. Online Store > Navigation > Collection and search filters
  2. Ensure filters are enabled for this collection
  3. Verify your theme supports Storefront Filtering
{%- endcomment -%}

Frequently Asked Questions