Skip to main content

Common Errors and Solutions

Solutions to common errors encountered when developing O2VEND themes and apps.

Template Errors​

Error: Variable not defined​

Problem:

Liquid Error: 'product' is not defined

Solution:

{% if product %}
  {{ product.name }}
{% else %}
  <p>Product not found</p>
{% endif %}

Error: Filter not found​

Problem:

Liquid Error: Unknown filter 'custom_filter'

Solution:

  • Check filter name spelling
  • Verify filter is registered
  • Use default filter as fallback:
{{ value | custom_filter | default: value }}

Error: Section not found​

Problem:

Liquid Error: Section 'header' not found

Solution:

  1. Verify section file exists: sections/header.liquid
  2. Check file name matches exactly
  3. Ensure section is in correct directory

Widget Errors​

Error: Widget not rendering​

Problem: Widget doesn't appear on page

Solution:

{% if widgets.content.size > 0 %}
  {% for widget in widgets.content %}
    {% if widget.template_path %}
      {% render widget.template_path, widget: widget %}
    {% else %}
      <p>Widget template not found: {{ widget.type }}</p>
    {% endif %}
  {% endfor %}
{% endif %}

Error: Widget settings not working​

Problem: Widget settings don't apply

Solution:

{{ widget.settings.title | default: 'Default Title' }}

API Errors​

Error: 401 Unauthorized​

Problem: API request returns 401

Solution:

  1. Check API key is correct
  2. Verify API key is in header:
headers: {
  'Authorization': `Bearer ${apiKey}`
}
  1. Check token expiration

Error: 404 Not Found​

Problem: API endpoint returns 404

Solution:

  1. Verify endpoint URL is correct
  2. Check API version (v1 vs v2)
  3. Ensure endpoint exists in API specification

Error: 429 Too Many Requests​

Problem: Rate limit exceeded

Solution:

  1. Implement request throttling
  2. Cache API responses
  3. Batch multiple requests
  4. Wait before retrying

Asset Errors​

Error: Asset not found​

Problem:

Asset 'theme.css' not found

Solution:

  1. Verify file exists in assets/ directory
  2. Check file name spelling
  3. Use asset_url filter:
{{ 'theme.css' | asset_url | stylesheet_tag }}

Error: Image not loading​

Problem: Images don't display

Solution:

{% if product.image %}
  <img src="{{ product.image | img_url: 'large' }}" 
       alt="{{ product.name | escape }}">
{% else %}
  <img src="{{ 'placeholder.png' | asset_url }}" alt="No image">
{% endif %}

App Errors​

Error: App not loading​

Problem: App doesn't activate

Solution:

  1. Check app.json syntax
  2. Verify app structure
  3. Check for JavaScript errors in console
  4. Verify hooks are correctly named

Error: Hook not executing​

Problem: App hook doesn't run

Solution:

  1. Verify hook name matches exactly
  2. Check hook is registered in app.json
  3. Ensure hook snippet exists
  4. Check for syntax errors in hook snippet

Debugging Tips​

1. Enable Debug Mode​

{% if settings.debug_mode %}
  <pre>{{ product | json }}</pre>
{% endif %}

2. Check Console​

Open browser console to see JavaScript errors

3. Use Liquid Debug​

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

4. Test in Isolation​

Test components individually to isolate issues

Getting Help​

If you encounter errors not covered here:

  1. Check the FAQ
  2. Review Debugging Guide
  3. Check Known Issues
  4. Search documentation
  5. Contact support