Troubleshooting Guide 8 min read

"Section id must exist" and Other Shopify Dev Theme Preview Errors

A theme that works on the live store throws errors or 404s on a development theme. Three causes account for most of it, and all three are visible in the template JSON before you push.

TS
ThemeSync Team
JSON template with an orphaned id in the order array causing Section id must exist
The cause of “Section id must exist”: an id in order with no section behind it.

Why it works live and fails in preview

A Shopify theme is code plus JSON that references things outside the theme: installed apps, metafield definitions, specific collections and files. The live store has all of them. A development theme pushed to a different store, or a theme moved between client stores, often doesn't.

Development themes also behave differently with apps. Some app extensions aren't available until an app is set up for that theme, and app embeds configured in settings_data.json may point at an app that isn't installed where you're previewing.

We built detection for these three cases into ThemeSync because they made up most of the "the preview is broken" messages we saw. The rules below are the same ones it runs.

Cause 1: app blocks and embeds

templates/product.json: an app block reference
"blocks": {
  "reviews_8kT2": {
    "type": "shopify://apps/judge-me-reviews/blocks/preview_badge/61ccd3b1-a9f2-4160-9fe9-4fec8413e5d8",
    "settings": {}
  }
}

How to find them: search every file in templates/ and config/settings_data.json for shopify://apps/. The segment after apps/ is the app's handle.

Terminal listing app block references in a theme
One command lists every app a theme depends on.
List every app a theme depends on
grep -rhoE 'shopify://apps/[a-z0-9-]+' templates config | sort | uniq -c

The fix: install the app on the preview store, or temporarily remove the blocks for preview. If you remove them, keep a backup of the original templates and restore them before anything goes live. Our article on app blocks as a QA blind spot covers testing them once they're back.

Cause 2: "Section id must exist"

An orphaned id in the order array
Brokenerror
  • sections: { "main": {...}, "faq": {...} }
  • order: ["main", "reviews_app", "faq"]
  • "reviews_app" was removed from sections but not from order
  • Result: the template fails with "Section id must exist"
Fixedrenders
  • sections: { "main": {...}, "faq": {...} }
  • order: ["main", "faq"]
  • Every id in order exists in sections
  • Apply the same check to block_order inside each section

This usually follows cause 1: an app section was stripped from sections but its id stayed in order. The same applies to block_order inside a section. It also happens when someone hand-edits JSON or copies a template between themes.

The fix: for each template, remove any id from order that isn't a key in sections, and any id in a section's block_order that isn't a key in its blocks.

Find orphaned ids (Node, run from the theme root)
const fs = require('fs');
for (const f of fs.readdirSync('templates').filter(f => f.endsWith('.json'))) {
  const raw = fs.readFileSync('templates/' + f, 'utf8').replace(/^\s*\/\*[\s\S]*?\*\//, '');
  const t = JSON.parse(raw);
  const missing = (t.order || []).filter(id => !(id in (t.sections || {})));
  if (missing.length) console.log(f, 'order references missing:', missing);
}

Shopify adds an auto-generated comment to the top of some JSON files, which is why the snippet strips a leading block comment before parsing.

Cause 3: "Dynamic source does not exist"

A setting bound to a metafield
"settings": {
  "text": "{{ product.metafields.custom.care_instructions | metafield_tag }}"
}

Metafield definitions belong to the store, not the theme. Push this template to a store without a custom.care_instructions product definition and the setting has nothing to resolve. Depending on where it's used, you get an editor error, an empty block, or a failed page.

How to find them: search templates, sections, snippets and layout for (product|collection|page|blog|article).metafields. and list each namespace and key.

The fix: create the same definitions on the preview store (same namespace, key and type), or clear those dynamic sources for preview and restore them afterwards. Full detail is in why sections render empty.

How ThemeSync handles all three

Under QA & Screenshots → Compatibility, ThemeSync scans a theme for app blocks and embeds (shopify://apps/ in templates and settings_data.json) and for metafield dynamic sources, and lists what it finds by app and file. The overview's Theme health card shows the count.

ThemeSync Theme compatibility with a Judge.me app embed detected
Compatibility: detected app embeds and metafields, with Strip for preview.
ThemeSync Theme health card showing code scan, image sources, app-block compatibility and screenshot status
The Theme health card on a theme’s overview page.

Strip for preview then removes app blocks from JSON templates, cleans up order and block_order so no orphaned ids are left, clears metafield dynamic sources, and backs up the originals to .app-blocks-backup (which is added to .shopifyignore). Turning it off restores the templates. One limit to know: app embeds in settings_data.json are detected and listed but not stripped.

Takeaways

  • Most dev theme preview errors come from references outside the theme: apps, metafield definitions and leftover section ids.
  • Search for shopify://apps/ to list every app a theme depends on.
  • "Section id must exist" means order or block_order lists an id that isn't defined.
  • "Dynamic source does not exist" means a metafield definition is missing on that store.
  • If you strip anything for preview, back it up and restore it before go-live.

Find preview-breaking references before the client does

ThemeSync lists app blocks and metafield sources per template, strips them for preview with a backup, and restores them in one click.

Try ThemeSync Free →