Debugging

Template errors happen. A missing variable, a typo in a filter name, or a broken loop can leave you with blank output or a confusing page. This guide covers how to find and fix these problems.

How errors work

When Quill hits an error during rendering, it does not crash the page. In production, a broken section renders as an empty block. The rest of the page loads normally. This keeps your storefront running even when a template has a problem.

In the visual editor, errors are shown inline. You see the error message, the line number, and a description of what went wrong. Fix the issue and the preview updates right away.

Common errors

Undefined variable

Undefined variable: prodcut

This means you used a name that does not exist. It is usually a typo. Check the spelling:

<!-- Wrong -->
{{ prodcut.title }}

<!-- Right -->
{{ product.title }}

Undefined filter

Undefined filter: monye

Same idea, but for a filter name. Check the spelling and make sure you are using a filter that exists:

<!-- Wrong -->
{{ product.price | monye }}

<!-- Right -->
{{ product.price | money }}

Unexpected end of template

Unexpected end of template: missing endfor

You opened a tag but did not close it. Every {% if %} needs an {% endif %}. Every {% for %} needs an {% endfor %}.

<!-- Missing endif -->
{% if product.available %}
  <p>In stock</p>

<!-- Fixed -->
{% if product.available %}
  <p>In stock</p>
{% endif %}

Wrong number of arguments

Wrong number of arguments for "truncate": expected 1-2, got 0

Some filters need arguments. Check the filter reference for the right syntax:

<!-- Wrong -->
{{ product.title | truncate }}

<!-- Right -->
{{ product.title | truncate: 50 }}

Debugging techniques

Print a variable

The simplest debugging tool. Output a variable to see what it contains:

<pre>{{ product | json }}</pre>

The json filter converts the object to a JSON string. This shows you every property and its current value. Remove the debug output when you are done.

Check for nil

If something is not showing up, it might be nil. Test for it:

{% if product.featured_image %}
  <p>Image exists</p>
{% else %}
  <p>Image is nil</p>
{% endif %}

Inspect a loop

When a loop produces unexpected results, add debug output inside it:

{% for product in collection.products %}
  <p>{{ forloop.index }}: {{ product.title }} ({{ product.available }})</p>
{% endfor %}

This shows the index, title, and availability for each item. You can spot missing products or wrong values quickly.

Check the size

If a collection seems empty, check its size:

<p>Products: {{ collection.products | size }}</p>
<p>Available: {{ collection.products | where: 'available', true | size }}</p>

Use assign to isolate values

Break a complex expression into steps to find which part is wrong:

{% assign raw_price = product.price %}
{% assign formatted = raw_price | money %}
<p>Raw: {{ raw_price }}</p>
<p>Formatted: {{ formatted }}</p>

Blank output

When a section or template renders nothing at all, check these things in order:

Is the variable nil? Use {{ variable | json }} to check.
Is the collection empty? Check {{ collection.products | size }}.
Is a condition wrong? Your if statement might be blocking all output. Add an else branch to confirm.
Is whitespace hiding the output? Use {%- -%} to strip whitespace if needed. Or check that your CSS is not hiding the element.
Is there a typo? Template tags with typos are silently ignored. Check every tag name.

Performance

If a page loads slowly, the template might be doing too much work. Look for these patterns:

Nested loops that multiply the number of iterations. A loop inside a loop with 100 items each runs 10,000 times.
Large collections without pagination. Use {% paginate %} for any collection with more than 50 products.
Repeated filter chains. If you use the same filter chain in multiple places, store the result with {% assign %} and reuse it.

<!-- Slow: runs the filter chain twice -->
<h2>{{ collection.products | where: 'available', true | size }} in stock</h2>
<p>{{ collection.products | where: 'available', true | size }} products ready to ship</p>

<!-- Better: filter once, use twice -->
{% assign available = collection.products | where: 'available', true %}
<h2>{{ available | size }} in stock</h2>
<p>{{ available | size }} products ready to ship</p>

On this page