shopify-liquid-rescue

Quick checklist

1. Lint first: from the theme root run shopify theme check --fail-level suggestion. Fix every reported error before pushing.
2. Authenticate: run any shopify theme … command and complete the verification code shown (opens accounts.shopify.com/activate-with-code).
3. Select the target theme: Shopify CLI only prompts interactively once. In non-interactive sessions always pass --store <store>.myshopify.com --theme <theme_id>.
4. Push & verify: shopify theme push --store <store>.myshopify.com --theme <theme_id> and read every error before retrying.

---

CLI workflow

1. Login flow

shopify theme list --store <store>.myshopify.com

• Copy the verification code + URL from the CLI output, open it in a browser, and log in.
• Repeat until the command prints your theme table (name / role / id).

2. Push a specific theme (non-interactive safe)

shopify theme push \
  --store <store>.myshopify.com \
  --theme <theme_id>

• Use shopify theme list to find <theme_id> (e.g., #157051879652).
• If the CLI warns “Failed to prompt: Select a theme…”, rerun with --theme set.

3. Common auth pitfalls

• Repeated login prompts: The CLI stores tokens per machine. If shopify theme push still asks for a code, re-open the provided URL, finish login, then re-run the command.
• CI usage: Always pass --store and --theme (no interactive selection available).

---

Liquid schema debugging

Validate section settings

Shopify enforces strict defaults:

• "type": "url" settings: the default must be a non-empty string (e.g., "/collections/all") or the default key should be omitted entirely. A blank string ("") or leaving the key present but empty triggers default must be a string / can't be blank errors.
• templates/*.json: every Section type must match a real file in sections/. If you add "waterbuds-hero" to templates/index.json, ensure sections/waterbuds-hero.liquid exists and is committed.

Fix process

1. Open the file reported in the error (e.g., sections/waterbuds-hero.liquid).
2. Adjust the schema block (remove/adjust invalid defaults, confirm type values, etc.).
3. Re-run shopify theme check to confirm.
4. Push again.

---

Packaging themes manually

When handing off a ZIP instead of using the CLI:

zip -r ../theme-upload.zip . -x "*.git*" "*.DS_Store"

The archive root must contain assets/, config/, layout/, locales/, sections/, snippets/, etc.—no extra parent folder.

---

Troubleshooting reference

Symptom	Likely cause	Fix
Invalid schema: setting ... default must be a string or datasource access path	Blank/defaultless url setting left in schema	Either remove the default line or set it to a valid string path.
Section type 'xyz' does not refer to an existing section file	JSON template references a section file that isn't present (typo or missing file)	Create/rename the section file under sections/ to match the type string.
CLI loops on “Select a theme to push”	Running in non-interactive environment without --theme	Pass --theme <id> or make the shell interactive.
CLI keeps asking for login	Token not stored yet	Visit the provided verification URL/code and sign in, then rerun the command.

Use this skill whenever dashboard deployments fail. It keeps the workflow consistent: lint → authenticate → target → push → fix errors quickly.