Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Shopify/horizon/llms.txt

Use this file to discover all available pages before exploring further.

​
Quick Diagnostics

Before diving into specific issues, run these quick checks:
1

Clear cache

Clear your browser cache and Shopify’s theme cache:
  • Browser: Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)
  • Shopify Admin: Online Store > Themes > Actions > Edit code (forces cache clear)
2

Run Theme Check

shopify theme check
This identifies common issues with your theme code.
3

Check browser console

Open DevTools (F12) and look for errors in the Console tab.
4

Verify Shopify CLI version

shopify version
Update if you’re not on the latest version:
npm install -g @shopify/cli@latest

​
Installation & Setup Issues

​
Git Clone Fails

Problem: SSH key not configured with GitHub.Solution: Use HTTPS instead of SSH:
git clone https://github.com/Shopify/horizon.git
Or configure SSH keys:
  1. Generate SSH key: ssh-keygen -t ed25519 -C "your_email@example.com"
  2. Add to GitHub: Settings > SSH and GPG keys > New SSH key
Problem: Incorrect repository URL or access permissions.Solution: Verify the URL:
git clone https://github.com/Shopify/horizon.git
Check you’re not trying to clone a private fork without access.

​
Shopify CLI Connection Issues

Problem: Authentication or network issues.Solution:
  1. Log out and log back in: 
    shopify auth logout
shopify auth login
  2. Verify you have the correct permissions:
    • Store owner or staff account
    • “Manage themes” permission enabled
  3. Check firewall/network settings:
    • Ensure ports 9292 (default dev server) are not blocked
    • Disable VPN if causing issues
Problem: Network timeout or file conflicts.Solution:
  1. Check file size limits (assets > 20MB will fail)
  2. Verify file names don’t contain special characters
  3. Try pushing/pulling specific files: 
    shopify theme push --only sections/header.liquid
  4. Use --allow-live flag carefully for live themes: 
    shopify theme push --allow-live

​
Theme Development Issues

​
Local Development Server

Problem: Port conflict or CLI issues.Solution:
  1. Check if port 9292 is in use: 
    # On macOS/Linux
lsof -i :9292

# On Windows
netstat -ano | findstr :9292
  2. Use a different port: 
    shopify theme dev --port 9293
  3. Kill any stuck processes and restart
Problem: Caching or sync issues.Solution:
  1. Hard refresh the browser (Ctrl+Shift+R)
  2. Disable browser cache in DevTools (Network tab > Disable cache)
  3. Check the terminal for sync errors
  4. Restart the dev server
  5. For CSS/JS changes, check file is being loaded:
    • Open DevTools > Network tab
    • Filter by CSS or JS
    • Look for 304 (cached) vs 200 (fresh) status

​
Liquid Errors

Problem: Invalid Liquid code causing rendering errors.Common causes:
  • Missing closing tags ({% endif %}, {% endfor %})
  • Typos in variable names
  • Invalid filter usage
  • Mismatched quotes
Solution:
  1. Check the error message for line number
  2. Verify all tags are properly closed
  3. Use Theme Check to identify issues: 
    shopify theme check
Example error:
{%- if product.available -%}
  <!-- Missing endif -->
Fix:
{%- if product.available -%}
  <button>Add to cart</button>
{%- endif -%}
Problem: Accessing undefined variables or properties.Solution:
  1. Check variable exists before using: 
    {%- if product.featured_image -%}
  {{ product.featured_image | image_url: width: 750 }}
{%- endif -%}
  2. Use default filter for fallbacks: 
    {{ product.title | default: 'Untitled Product' }}
  3. Verify you’re in the correct template context:
    • product only available on product templates
    • collection only on collection templates
    • Use {% echo %} to debug: {% echo product %}
Problem: Using deprecated or incorrect filters.Solution:
  1. Check Liquid filter documentation
  2. Verify parameter syntax: 
    {%- comment -%} Correct {%- endcomment -%}
{{ product.featured_image | image_url: width: 750 }}

{%- comment -%} Incorrect {%- endcomment -%}
{{ product.featured_image | image_url: 750 }}
  3. Some filters require specific input types: 
    {%- comment -%} money filter needs cents {%- endcomment -%}
{{ 1999 | money }}  {%- comment -%} $19.99 {%- endcomment -%}

​
JavaScript Errors

Problem: Variable or function not defined.Solution:
  1. Check script load order in layout/theme.liquid: 
    {{ 'global.js' | asset_url | script_tag }}
{{ 'product.js' | asset_url | script_tag }}  {%- comment -%} Loads after global {%- endcomment -%}
  2. Verify modules are exported/imported correctly: 
    // product.js
export class ProductForm { }

// main.js
import { ProductForm } from './product.js';
  3. Check for typos in variable/function names
Problem: Elements not found or timing issues.Solution:
  1. Verify element exists when code runs: 
    // Bad - might run before DOM ready
const button = document.querySelector('.add-to-cart');
button.addEventListener('click', handler);

// Good - waits for DOM
document.addEventListener('DOMContentLoaded', () => {
  const button = document.querySelector('.add-to-cart');
  button?.addEventListener('click', handler);
});
  2. Use event delegation for dynamic elements: 
    document.addEventListener('click', (event) => {
  if (event.target.matches('.add-to-cart')) {
    // Handle click
  }
});
  3. Check element isn’t disabled or hidden
Problem: Cross-origin request blocked.Solution:
  1. Use Shopify’s Ajax API for cart/product operations: 
    fetch('/cart/add.js', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ id: variantId, quantity: 1 })
})
  2. For external resources, ensure CORS headers are set on the server
  3. Use proxy for third-party APIs if needed

​
Styling Issues

​
CSS Not Loading

Problem: CSS file not loaded or incorrect path.Solution:
  1. Verify asset_url in layout: 
    {{ 'base.css' | asset_url | stylesheet_tag }}
  2. Check file exists in /assets/ directory
  3. Clear browser cache and hard refresh
  4. Check Network tab in DevTools:
    • 404 error = file not found
    • 304 = cached (might be outdated)
Problem: CSS specificity or order issues.Solution:
  1. Increase specificity without using !important: 
    /* Less specific */
.button { }

/* More specific */
.product-form .button { }
  2. Check stylesheet load order: 
    {{ 'base.css' | asset_url | stylesheet_tag }}
{{ 'custom.css' | asset_url | stylesheet_tag }}  {%- comment -%} Loads after base {%- endcomment -%}
  3. Use DevTools to inspect which rules are applied:
    • Right-click element > Inspect
    • Check Styles panel for crossed-out rules
Problem: CSS custom properties not defined or inherited.Solution:
  1. Define variables on :root or appropriate scope: 
    :root {
  --color-primary: #000F9F;
}

.button {
  background-color: var(--color-primary);
}
  2. Check for typos in variable names (case-sensitive)
  3. Provide fallback values: 
    color: var(--color-text, #000000);

​
Version-Specific Issues

​
v3.4.0 Update Issues

Problem: Customer account menu broken after upgrading to v3.4.0.Solution:
  1. Clear browser cache completely
  2. Check for JavaScript console errors
  3. Verify custom CSS isn’t targeting old account menu selectors
  4. If heavily customized, review migration guide for account component changes
Problem: Product cards displaying at wrong widths.Solution:
  1. Check new width control settings in section schema:
    • Desktop width setting
    • Mobile width setting
  2. Test responsive behavior at different breakpoints
  3. Clear any custom CSS that might conflict: 
    /* Remove fixed widths if present */
.product-card {
  /* width: 300px; */ /* Remove this */
}

​
Performance Issues

Problem: Poor performance metrics.Solution:
  1. Run Lighthouse audit (Chrome DevTools):
    • Right-click > Inspect > Lighthouse tab
    • Generate report
    • Follow recommendations
  2. Optimize images: 
    {%- comment -%} Use responsive images {%- endcomment -%}
{{ product.featured_image | image_url: width: 750 }}

{%- comment -%} Add loading="lazy" {%- endcomment -%}
<img loading="lazy" ... >
  3. Minimize JavaScript:
    • Remove unused scripts
    • Defer non-critical JS
    • Use code splitting
  4. Enable asset preloading: 
    <link rel="preload" href="{{ 'base.css' | asset_url }}" as="style">
Problem: LCP metric failing Core Web Vitals.Solution:
  1. Identify LCP element (usually hero image or heading)
  2. Preload LCP image: 
    {%- if section.settings.image -%}
  <link
    rel="preload"
    as="image"
    href="{{ section.settings.image | image_url: width: 1500 }}"
  >
{%- endif -%}
  3. Use loading="eager" for above-fold images: 
    <img loading="eager" ... >
  4. Optimize image file size (compress without quality loss)
Problem: Elements shifting during page load.Solution:
  1. Set explicit dimensions on images: 
    <img
  width="{{ image.width }}"
  height="{{ image.height }}"
  ...
>
  2. Reserve space for dynamic content: 
    .product-card__image {
  aspect-ratio: 1 / 1;
}
  3. Avoid inserting content above existing content
  4. Use CSS containment: 
    .product-card {
  contain: layout;
}

​
Browser-Specific Issues

Common Safari issues:
  1. Flexbox bugs: Use explicit flex properties 
    .flex-item {
  flex: 1 1 auto; /* Instead of just flex: 1 */
}
  2. Date input styling: Safari doesn’t support custom date pickers well 
    input[type="date"]::-webkit-calendar-picker-indicator {
  display: block;
}
  3. Position fixed in iOS: Avoid fixed positioning during scroll
Common Firefox issues:
  1. Flexbox gaps: Firefox handles gap differently in older versions 
    .flex-container {
  gap: 1rem;
  /* Fallback for older Firefox */
  margin: -0.5rem;
}
.flex-container > * {
  margin: 0.5rem;
}

​
Getting Additional Help

Shopify Community

Search or ask questions in the Shopify Community Forums

Shopify Support

Contact Shopify Support for store-specific issues

Theme Documentation

Review Shopify Theme Documentation

GitHub Issues

Check Horizon GitHub Issues for known bugs

​
Debug Mode

Enable Shopify’s debug mode to see detailed error messages: 
{%- comment -%} Add to layout/theme.liquid {%- endcomment -%}
{% if request.host contains 'myshopify.com' %}
  <script>window.Shopify.designMode = true;</script>
{% endif %}
Remove debug code before going live to avoid exposing sensitive information.

​
Reporting Bugs

When reporting issues:
  1. Provide context:
    • Horizon version (check config/settings_schema.json)
    • Browser and version
    • Steps to reproduce
  2. Include error messages:
    • Browser console errors
    • Theme Check output
    • Server-side Liquid errors
  3. Share code samples:
    • Minimal reproducible example
    • Relevant Liquid/JS/CSS code
  4. Screenshots/videos:
    • Visual bugs benefit from images
    • Use browser DevTools to highlight issues

Build docs developers (and LLMs) love

Get started for freeTalk to us