Troubleshooting
Common theme problems and how to resolve them.
“This theme isn’t built yet”
The active/previewed theme has no usable views/pages/layout.liquid (or a page
template is missing). Check the file exists and outputs the three required
platform tags. For a custom fork, a missing page falls back to the starter — see
Custom themes.
A publish was rejected (422)
The Quality Gate blocked it. The error names
the file, line, and rule. Run cartisto theme validate locally to reproduce and
fix, then publish again. The live store was never touched.
push reports conflicts (409)
Your local file’s base version is behind the server’s — someone (or a publish)
changed it. cartisto theme pull to refresh, reconcile, then push. After a
--publish, the CLI refreshes its version baselines automatically.
Preview looks unstyled
Confirm layout.liquid links {{ 'css/theme.css' | asset_url }} and that your
CSS compiled. In preview, draft CSS is served with no-cache; a hard refresh
clears a stale copy.
A template renders blank where I expected data
Liquid is lenient — a missing/typo’d variable renders empty rather than erroring.
Check the object name against Liquid objects, and
remember {% render %} partials only see the data you pass plus the page globals.
A Liquid syntax error
In preview you’ll see the full error with the file and line; shoppers never see it (the live store keeps serving the last published version). Fix the file and save again.
Prices look wrong
Don’t compute prices in templates — they arrive already converted. Use money /
money_format. If a number is off, it’s a data/currency-settings issue, not a
template one.
cartisto doctor
When something’s off with the CLI itself — wrong store, expired key, missing
scope — cartisto doctor checks Node, the CLI version, the active profile, and
the key’s connection and themes scope in one shot.