Debugging Shopify Liquid on Production Themes (Without Breaking the Live Store)

Sales notifications pinging Slack while Liquid throws a 500 on the live storefront is a specific kind of stress. Nishad Kikani documents the duplicate-theme workflow, error patterns, and schema failures K2 Devworks uses when debugging production themes — never live-first, always with a rollback plan the merchant understands.

Production Liquid debugging is a different skill from writing greenfield sections on a calm dev store. The bug is visible to customers, the merchant is in the admin panicking, and the fastest "fix"—commenting out half of product.liquid—can cost more than the bug. We have a disciplined workflow we use on client emergencies and quieter maintenance weeks alike. It prioritizes customer safety, reproducibility, and fixes that stay fixed after the next app update. If you are newer to Liquid syntax, keep Liquid for Beginners and the cheat sheet open—but this article is about battlefield procedure.

Rule zero: duplicate theme first

Never debug interactively on the live published theme during business hours unless the site is already down and rollback failed. Duplicate the theme, reproduce on the duplicate, fix, preview share link to client, publish duplicate when approved. Shopify's theme duplicate is underrated insurance. We name duplicates DEBUG-2026-06-15-issue slug so six months later nobody publishes the wrong one. Document which duplicate is canonical after publish.

Classify the failure before touching code

• Hard Liquid error — 500-style failure, blank section, "Something went wrong" in editor; often syntax, schema JSON, or infinite loop
• Soft logic bug — page renders but wrong data, missing collection, inverted if condition
• Editor-only bug — storefront fine, customizer broken; often schema or shopify_attributes
• App collision — works until app installs; script overrides or duplicate markup
• Data issue — metafield empty, variant policy, market pricing—not Liquid at all

Misclassification wastes hours. A "broken hero" once was an unpublished market catalog. Confirm product, collection, and customer context before rewriting loops.

Liquid errors we see most often

Unclosed tags and mismatched endif

{% if collection.products.size > 0 %}
  {% for product in collection.products %}
    {{ product.title }}
  {% endfor %}
{% comment %} MISSING {% endif %} — breaks entire template {% endcomment %}

One missing endif can white-screen a template. theme-check flags many of these; run it locally before Git push. In emergencies, binary-search comment out large Liquid blocks to isolate the offending file—restore immediately after locating.

Nil object access without guards

{%- if product.selected_or_first_available_variant != blank -%}
  {{ product.selected_or_first_available_variant.price | money }}
{%- endif -%}

{%- comment -%} Safer than assuming product exists on every template {%- endcomment -%}
{%- if product -%}
  ...
{%- endif -%}

Search templates and sections for raw {{ product. without surrounding if product. Featured sections on non-product templates are a common culprit when merchants add sections globally.

Broken schema JSON

{% schema %}
{
  "name": "Broken example",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", }  
  ]
}
{% endschema %}

That trailing comma after "Heading" invalidates the section—editor shows a cryptic error, sometimes the whole template refuses to customize. Copy schema into a JSON validator. Compare against patterns in Schema Guide.

Safe inspection techniques (no console.log)

Liquid runs server-side; browser devtools only see output HTML. Techniques we use: HTML comment debug wrappers visible in view-source—{% comment %} DEBUG: collection={{ collection.handle }} {% endcomment %}; temporary visible pre blocks gated by ?debug=1 query handling via JavaScript—not ideal but merchants rarely add query strings; compare rendered HTML between working duplicate and broken theme using diff tools; export theme, ripgrep for suspicious patterns across sections/. Remove all debug output before publish—comments leak in page source.

Debugging section.settings and blocks

When merchants "changed the heading but nothing updated," check three places: wrong section instance on a duplicate homepage JSON entry; setting id renamed in schema but old JSON still stores previous id—Liquid returns blank; dynamic source set to metafield that is empty. For blocks, verify block.type in case matches schema block types exactly—faq_row vs faq-row breaks silently. See Liquid mistakes we still see for parallel patterns.

{% for block in section.blocks %}
  {% case block.type %}
    {% when 'faq_row' %}
      ...
    {% else %}
      {% comment %} DEBUG: unknown block type {{ block.type }} {% endcomment %}
  {% endcase %}
{% endfor %}

Soft logic bug playbook

When the page renders but data is wrong, log the template context mentally: which template, which section instance, which collection or product object. Compare section.settings in editor sidebar against values in templates JSON on disk—they diverge after editor saves. For collection loops, verify collection setting points to the intended handle, not an empty fallback. For product references inside sections on non-product templates, confirm you used product pickers, not the global product object which may be blank. These bugs feel like Liquid failures but are configuration errors merchants introduced innocently.

Snippets, renders, and parameter drift

Shared snippets break when one caller passes variant: product.selected_or_first_available_variant and another omits it. Grep all {% render 'snippet-name' %} calls when debugging inconsistent cards. Snippet parameters are not optional unless you use default filters—document required params in snippet comment headers. After renaming snippet files, stale renders fail silently in some themes with empty output. theme-check catches missing snippets; human review catches wrong params.

Editor preview loads admin context—different scripts, Translation API, accelerated checkout buttons. Bugs that appear only live often involve: cart AJAX endpoints, customer login state, or market-specific pricing. Test logged-out and logged-in, US and international markets if enabled. Dawn's cart drawer behaves differently than page cart templates—reproduce on the actual template merchants use.

Git, deploys, and partial uploads

Shopify CLI push can fail mid-theme; some files update, others do not. Symptom: "works locally, broken on store" with no obvious error—compare file checksums or re-push entire sections/ folder. GitHub integration merge conflicts silently drop template JSON blocks. After every deploy, spot-check one product, one collection, cart. Maintain a deploy log on client projects.

Reading Shopify error surfaces

Liquid errors sometimes surface only in theme editor overlay, not on the public storefront—editor runs additional validation. Check browser console on customize preview for 404 section files. Admin > Online Store > Themes > Actions > Edit code shows file list; confirm uploads landed. For persistent "Upload failed" on large assets, split CSS or remove BOM from UTF-8 files. Windows editors occasionally inject BOM into .liquid files and break schema parsing in subtle ways.

When to escalate to Shopify Support versus fix in theme

Checkout bugs outside theme scope, tax miscalculation, payment gateway failures, and platform outages go to Shopify Support with reproduction steps. Theme bugs stay with agency. Gray zone: Markets pricing wrong on product cards—verify market configuration before rewriting Liquid. Plus merchants get faster support; document ticket numbers for client visibility. Do not burn retainer hours fighting platform bugs disguised as theme bugs.

Performance-related "bugs"

Sometimes the bug is timeout from nested loops—{% for product in collections.all.products %} on homepage—or massive images without width filters. These manifest as intermittent blanks on slow connections, not deterministic Liquid errors. Profile with Chrome throttling; fix loops and image_url widths. Read performance checklist.

Creating minimal reproduction themes

When bugs are elusive, strip down: duplicate theme, remove all custom sections except the suspect, simplify template JSON to one section, add complexity back one piece at a time. Binary search is faster than reading entire theme.liquid under pressure. Save reproduction themes named REPRO-issue-123 so you can return to them if clients regress. Share reproduction steps with app vendors—they need minimal cases, not your entire 400-file theme.

Logging fixes in team knowledge base

Every non-obvious production fix becomes a short internal note: symptom, root cause, file, prevention. Patterns emerge—trailing comma in schema, missing endif after rush deploy, app block_order migration. New developers onboard faster when debugging history is searchable. Redact client names; keep technical detail. We tag notes by cluster: cart, product, schema, apps—mirroring how common mistakes are categorized.

Collaboration with apps and third parties

When an app update coincides with a bug, reproduce with app disabled in duplicate theme—not uninstall on live. Document findings for vendor tickets: theme version, section type, block type URL, screenshot, expected versus actual. Agencies that blame apps without reproduction lose credibility; apps that blame "custom theme" without checking @app slots waste everyone's time.

Building a vendor ticket that gets fixed

Include store URL (password if needed), theme name and version, steps to reproduce in under ten clicks, expected versus actual screenshot, browser and device, and confirmation the bug disappears on Dawn with only that app installed. Vendors ignore vague "cart broken" reports. Precise reports get engineering attention. Save duplicate themes named VENDOR-appname-issue for reuse when the same app appears on multiple clients.

Post-incident hardening

1. Add theme-check to CI if missing
2. Add stress-test product and collection to dev store playbook
3. Document the root cause in client Notion—prevents repeat panic
4. If schema id rename caused data loss, add migration note or default fallbacks
5. Schedule duplicate theme cleanup so DEBUG themes do not accumulate

The fix is not done until you know why it broke on production but not in dev. Skip root cause and you will debug the same file next month.

Using theme-check and CI before production

theme-check should run on every pull request—SyntaxError in Liquid, deprecated include tags, missing templates, and invalid schema are caught before a merchant sees them. It will not catch logic bugs like showing the wrong collection, but it prevents embarrassing editor-breaking deploys. We configure allowed offenses explicitly so teams do not ignore the tool after noise fatigue. Pair theme-check with a mandatory preview URL comment on PRs. For schema-specific debugging, compare broken sections against exports from Liquid Schema Generator that are known valid.

Metafields, dynamic sources, and false Liquid bugs

A rising category of "Liquid bugs" is empty metafield output. The section is correct; the merchant never filled product metafields, or the namespace is wrong after a migration. Verify in admin before rewriting loops. Dynamic sources in schema connect settings to metafields—when the binding breaks, settings appear frozen. Document which sections use dynamic sources in handoff materials. Read Metafields Tutorial if your team is new to the data model.

Debugging cart and AJAX-driven sections

Cart drawer, predictive search, and quick-add modals fail differently than static sections—the initial Liquid render succeeds while JavaScript fetch fails. Open network tab, filter XHR, confirm /cart.js and section rendering endpoints return 200. Compare section ids in fetch query params against renamed ids in your customization. These bugs rarely show in static theme editor preview. Cross-reference cart drawer guide when symptoms involve stale line items.

Communication during live incidents

While debugging on duplicate theme, message the client with status every thirty minutes—even if the update is "still investigating." Silence amplifies panic. State what you ruled out, what you are testing next, and whether rollback is available. Merchants remember calm transparency. After resolution, send a short postmortem: root cause, fix, prevention step. That builds retainer trust and justifies theme-check or staging discipline investments they declined last quarter.

Emergency rollback procedure

If the live site is down: publish previous known-good theme duplicate immediately—merchants can do this without you if you pre-named BACKUP theme. Then debug calmly on a copy. Keep one backup duplicate untouched per major release. For single-section regressions, revert one file via Git history and CLI push faster than full theme rollback—if you are sure scope is isolated.

FAQ

Can I use console.log in Liquid?

No. Use theme-check, HTML comment debugging removed before publish, and duplicate theme isolation.

Why preview works but live fails?

Check published theme identity, template JSON divergence, markets, customer login state, and apps active only on live.

Next steps

Strengthen fundamentals with Common Liquid Mistakes and Loops Guide. Build new sections with validation from the converter to reduce schema typos that become production fires. Debugging is not glamorous—it is how senior theme developers earn trust on client stores.

Keep a personal incident log for one year—you will notice repeat patterns and automate preventions. The developers who look fastest in emergencies are usually the ones who refused to hotfix live without a duplicate theme and a written hypothesis.