Debugging Liquid: Common Errors and How to Fix Them

Liquid syntax errors surface as theme upload failures or red error banners in the theme editor. Common causes: unclosed {% if %} blocks, mismatched {% endfor %}, invalid filter arguments, and using {{ }} inside {% %} tags. Shopify's parser is strict; a single typo in sections/featured-collection.liquid can block the entire push.

JSON templates (templates/product.json) fail when section type paths are wrong, presets reference missing blocks, or trailing commas appear in JSON. The error message often points to line numbers in the JSON file, not the section Liquid. Fix by validating JSON in VS Code and running shopify theme check.

Whitespace control typos like {%- without closing -%} confuse editors but usually still parse. More subtle: using assignment inside output tags {{ assign x = 1 }} instead of {% assign x = 1 %}. When upload fails without a clear line, binary-search by commenting out half the section with {% comment %} blocks and re-push.

Liquid returns empty strings for nil properties in output tags, but conditions may behave unexpectedly. customer is nil for guests; accessing customer.orders without {% if customer %} shows nothing but may break JSON-LD if you output invalid JSON. product.selected_variant can be nil when no selection exists; use product.selected_or_first_available_variant.

Metafields return nil when unset: product.metafields.custom.size_chart without checking .value renders blank. Use {% if product.metafields.custom.size_chart.value != blank %}. For nested metaobjects, one missing link nils the chain—guard each level.

Snippet parameters passed via render are nil if omitted: {% render 'badge', label: badge_label %} when badge_label was never assigned. render isolates scope; parent assigns do not leak. Debug by temporarily outputting {{ variable | json }} in development only, then remove before production.

Shopify enforces Liquid iteration and render time limits. Loops over entire huge collections, nested loops (collections → products → variants), and recursive render patterns cause 'Liquid error: memory' or truncated output. Fix with limit:, paginate, and precomputed data in metafields.

forloop object helps debug: forloop.index, forloop.length, forloop.last. Break early with {% if forloop.index > 12 %}{% break %}{% endif %} where supported, or restrict in the loop header {% for item in collection.products limit: 12 %}.

capture blocks accumulating huge HTML strings in loops inflate response size and hurt TTFB. Move repeated markup to snippets rendered once per iteration without nested captures. Theme Check rules like TemplateLength and NestedSnippet warn before production incidents.

UndefinedObject flags variables used without guarantee they exist on that template—classic mistake: using collection on the cart page. RemoteAsset warns when hotlinking images instead of CDN filters. DeprecatedTag flags {% include %} and old jQuery patterns.

ParserBlockingJavaScript and stylesheet_tag overuse appear as warnings but correlate with real Lighthouse regressions. TranslationKeyExists catches missing locale keys before Hindi launch. Treat warnings as errors for checkout-adjacent templates.

Run shopify theme check --fail-level error in CI and review warning reports weekly. Autofix is limited; developers fix at source. Pair with editor integration so mistakes are caught at save time.

Reproduce in theme preview with ?preview_theme_id= on the affected template. Identify which JSON template assigned the section stack. Strip sections in theme editor to isolate the offending block, or duplicate the theme for destructive tests.

Use the browser inspector for rendered HTML issues (wrong variant price display) versus Liquid logic issues (nil metafield). For AJAX cart bugs, trace theme JavaScript fetch handlers separately from Liquid; cart.json responses are API-shaped, not template-shaped.

Log to Shopify admin theme editor error console when available, and keep a changelog of app installs—apps inject snippets that break layouts. Roll back via Git revert + theme pull, then push previous commit. ADSPOC maintains rollback tags on every client repo for this reason.

Document fixes in PR descriptions so teams do not repeat nil metafield access or unbounded loops. Good debugging discipline shortens launch timelines more than any single optimization trick.