Skip to main content

​
Liquid Theme Troubleshooting

Start with the symptom, then check the smallest likely cause.

​
shoppex theme dev Says The Theme Is Not Liquid

Cause: the folder does not contain theme-package.json. Fix: 
ls theme-package.json
If the file is missing, you are probably in the wrong directory. Pull a Liquid hosted theme: 
shoppex theme pull --theme 11111111-1111-4111-8111-111111111111 --out ./my-theme
cd ./my-theme
shoppex theme dev

​
Validation Fails With Missing Template

Cause: theme-package.json declares a section or snippet that does not exist, or a template renders an undeclared snippet. Fix:
  • confirm the file exists
  • confirm the path matches exactly
  • add it to paths.sections or paths.snippets
  • add or update the blocks registry entry if it is a renderable block
Simple example: {% render "snippets/product-card" %} requires snippets/product-card.liquid to be declared.

​
Dynamic Partial Is Rejected

Cause: merchant Liquid packages cannot render dynamic template paths. Wrong: 
{% render section.partial %}
Right: 
{% render "snippets/product-card", item: item %}

​
Builder Cannot Select A Section

Cause: the section root is missing Builder markers. Fix every renderable section root: 
<section
  data-builder-block="{{ block.id }}"
  data-builder-block-type="{{ block.type }}"
>
  ...
</section>

​
Local Preview Shows Fixture Data

Cause: shoppex theme dev uses fixture data by default. Use live data: 
shoppex theme dev --shop-slug my-shop --no-msw

​
Push Fails With Revision Mismatch

Cause: the remote draft changed after your last pull. Safe fix: 
shoppex theme pull --force
Only use force push when you intentionally want to replace newer remote changes: 
shoppex theme push --force

​
CSS Or Images Are Missing

Check:
  • asset exists under assets/
  • asset is declared in theme-package.json
  • stylesheet path is assets/built.css
  • template uses assetUrl
Example: 
<link rel="stylesheet" href="{{ 'assets/built.css' | assetUrl: ctx }}">

​
Add To Cart Does Nothing

Check:
  • {{ storefrontCommerceScriptHtml | raw }} is mounted in the layout
  • product form has x-data="productForm(...)" or product card has the expected platform controller
  • required product data is present in context
  • no custom script replaced platform cart behavior

​
Checkout Opens Wrong Or Not At All

Do not manually build invoice URLs. Let the platform runtime create the hosted checkout handoff. Check:
  • cart lines have product and variant ids
  • quantity is within allowed bounds
  • coupon UI uses platform runtime behavior
  • checkout modal or drawer snippets are mounted
  • merchant payment gateways are configured

​
Published Page Looks Stale

Check:
  1. You are on the live storefront, not an old preview URL.
  2. shoppex theme publish completed.
  3. The active artifact is the one you expect.
  4. Cache purge completed.
  5. Hard refresh the browser.

​
Server Render Fails On Missing Data

Do not add Liquid fallbacks for required contract data. Simple example: if product.stock is missing for a buy box, fix the producer/render context. Do not display “In stock” from Liquid.

​
Useful Checks

shoppex theme validate --include-typecheck
shoppex theme preview

​
Next Steps

Package Format

Confirm required files and manifest entries.

Core Contract

Review Liquid safety and producer responsibilities.