Common Shopify Liquid Mistakes

Errors that look like theme bugs

Most Liquid failures are omitted guards, wrong template scope, or schema mismatches—not mysterious syntax. In Shopify section work, we commonly catch these in code review before merge.

Syntax and nil values

<!-- Bad: comparing booleans to strings -->
{% if product.available == 'true' %}

<!-- Good -->
{% if product.available %}

Outputting nil objects prints nothing—check != blank before images, metafields, and optional settings.

Scope: wrong object on this template

product.title on index.json is empty. section.settings.heading works in sections but not in unrelated snippets unless passed explicitly via {% render %}.

Escaping and richtext

<h2>{{ section.settings.title | escape }}</h2>
<div class="rte">{{ section.settings.body }}</div>

Escape plain text settings; richtext and metafield_tag intentionally output HTML.

Loops and performance

• Unpaginated collection.products caps at 50 items silently
• <script> tags inside loops duplicate JS per iteration
• Triple-nested loops risk Liquid render timeouts on large catalogs

{% paginate collection.products by 24 %}
  {% for product in collection.products %}
    {% render 'card-product', product: product %}
  {% endfor %}
{% endpaginate %}

Editor integration

• Missing {{ block.shopify_attributes }} — blocks not selectable
• Missing presets — section absent from Add section
• Unscoped CSS — typography leaks across templates

Debugging workflow

1. Reproduce on a duplicate theme
2. Confirm template context (product vs index vs collection)
3. Match schema ids to Liquid exactly
4. Run Theme Check on changed files

Takeaway

Fix patterns once and enforce in review. Image-specific mistakes: Image Optimization Guide. Loop limits: Loops Guide.

Mistakes seniors still ship under deadline

Experience does not immunity—rushed Friday deploys still ship unscoped CSS, empty presets, and paginate omissions. Code review focused on schema and theme editor click paths catches most items below before merge.

7. Missing presets on custom sections

Without presets, merchants cannot add your section from the editor. Always include at least one preset with a clear name and realistic defaults.

8. Global CSS in sections

Unscoped h2 { font-size: 48px; } leaks into collection pages. Prefix selectors with #shopify-section-{{ section.id }}.

9. Hardcoding URLs

Use {{ routes.cart_url }} and url settings—not /cart paths that break on multi-market stores.

10. Unpaginated collection loops

Fifty-product cap is silent. Wrap with {% paginate %} on collection and blog templates.

11. Richtext without .rte wrapper

Merchant bold and links need theme typography styles—wrap {{ section.settings.body }} in <div class="rte">.

Production debugging workflow

1. Reproduce on duplicate theme, not live
2. Binary-search recent section deploys
3. Check theme editor vs storefront template mismatch
4. Run Theme Check on changed files

War stories layer: mistakes on client stores and debugging production themes.